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Visual Development Environment For 


WATCOM VX'Rexx is an easy to use visual development 
environment for creating applications that leverage the 
capabilities of OS/2 2.x and exploit the Presentation Manager 
graphical user interface. VX'Rexx combines a project 
management facility, visual designer and an interactive source- 
level debugger to deliver a very approachable and highly 
productive visual development environment. 


Design Applications 

Visually Create rich graphical 
applications quickly and easily using 
the visual design environment. With 
the visual designer, you can 
graphically create Presentation 
Manager interface objects, quickly 
customize their properties, and 
easily attach Rexx procedures using 
powerful drag-and-drop 
programming techniques. 


Integrated Development 
Environment Build, test and 

debug your application without 
leaving the development 
environment. Then package your 
application as an EXE file or PM 
macro for royalty-free redistribution. 
The power of the integrated 
development environment and 
debugger can also be used with your 
existing Rexx applications. 


Powerful Open 
Environment Enjoy the 

simplicity of event-driven 
programming together with the 
global editing capabilities 
essential for professional project 
management, WATCOM 
VX'Rexx is open and extensible 
through IBM’s object oriented 
System Object Model (SOM) 
technology. You can access all 
standard Rexx API’s including 
DB2/2, because VX'Rexx is 
based on the OS/2 2.x standard 
system Rexx. 


Highlights 


► Easy to use visual development environment 

► Create and modify objects dynamically at 
both edit and run time 

► Powerful project management facility 

► Advanced interactive source-level debugger 

► Package your applications as EXE files or 
PM macros 

► Access to standard Rexx API’s including 
DB2/2 

► System Object Model (SOM) based object 
manager 


► Drag-and-drop programming 

► Support for multi-threaded applications 

► Include OS/2 style help and hints in your 
applications 

► Supports SAA CUA’91 objects 

► Integrated console window support for 
existing Rexx programs 

► Royalty-free run-time 

► Multiple modeless window support 

► Create PM macros for applications 
supporting Rexx as a macro language 












OS/2 Rexx 


Interactive Debugging 

If an error occurs at run-time, 
VX*Rexx will display a traceback 
pinpointing the source line where 
the error occurred. A simple click 
of the mouse will return you to the 
source edit window to correct the 
error. The built-in interactive 
source-level debugger lets you set 
breakpoints, step through code 
and watch variables to track down 
complex problems. 


and easy 
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WATCOM International 

415 Phillip Street, Waterloo, Ontario, Canada, N2L 3X2 
Phone: (519) 886-3700 Fax: (519) 747-4971 


Suggested Retail: $199* 
Call Toll Free 

1 - 800 - 265-4555 

WATCOM 


Build Professional 
Applications 

WATCOM VX»Rexx allows 
you to leverage key OS/2 features 
to create professional applications. 
Build applications that dynamically 
create and modify CUA’91 screen 
objects at both edit and run-time, 
and include OS/2 style help and hints 


Create Multi-Threaded 

Applications Every VX*Rexx 
application contains multiple threads. 

One thread remains responsive to user 
input while others continue processing. 

In addition, VX»Rexx provides the 
ability for advanced applications to easily 
use additional threads. 
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VX*Rexx: 


The integrated visual 
solution builder for OS/2 2.x. 


‘Prices and specification are subject to change without notice. Price does not include freight and taxes where applicable Prices 
quoted in US dollars WATCOM. the Lightning Device, and VX*Rexx are trademarks of WATCOM International Corporation. Other 
trademarks are the properties of their respective owners. © Copyright 1993 WATCOM International Corporation 










44 We were told it was impossible 
to develop a client/server application 
without extensive retraining. 

Then we talked to Micro Focus. ^ 



Larrv Lowder, Systems Architect, Qucstar Service Corporation. 


Mountain Fuel Supply? a division of Questar? is a utility company 
supplying natural gas to 750,000 customers across Utah, Wyoming, Idaho 
and Colorado. The company’s success is largely driven by its implicit belief 
that the customer is number one. 

Yet, IT also plays its part in that success: client/server architectures and 
graphical user interfaces (GUIs) have helped Mountain Fuel Supply move 
applications and information closer to the customers and the employees. All 
of which has resulted in an augmented level of service being offered to 
customers. 

When Larry Lowder, one of Questar’s Systems Architects, set out to 
build the client/server architecture for Mountain Fuel Supply, he needed 
solutions, not skepticism. For the first project, a cashiering system, he 
needed to link workstations with OS/2* to the DB2* database on the host, 
running CICS? 

“We were faced with having to spend up to two years retraining our 



COBOL programmers in C and API calls. Then we discovered Micro Focus 
Dialog System? It allowed us to build the client functionality we required, 
and re-engineer the existing mainframe application as a server." 

“Within a week, mainframe programmers were producing GUI screens 
for COBOL. Within 90 days we had delivered the system. Now were not 
only coming in under budget, but also way ahead of schedule." 

As Mountain Fuel Supply discovered, the Micro Focus solution lets 
you make a productive transition to client/server without sacrificing any of 
the resources you’ve worked so hard to build. 

When the world’s leading corporations demand U A Better W ay of 
Programming ?” they turn to Micro Focus. For a brochure on putting the 
Micro Focus Client/Server Solution to work for you, call 800-872-6265. 

MICRO FOCUS 

Micro Focus Inc. 2465 East Bayshore Road, Palo Alto, CA 94303. Tel. (415) 856 4161. 


Micro Focus is a registered trademark and Dialog System and "A Better Way of Programming’ are trademarks of Micro Focus. Inc. All other trademarks are property of their respective companies 

GSA Contract Number GS00K93AGS6403. 
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SourceLink v2.0 

by One Up Corporation 

SourceLink, the ultimate 32-Bit programming 
development tool, combines the functionality of 
hyperlink source code access, a fully-functional 
editor and extensive flic manipulation utilities into 
one very powerful toolset. Now you can find code, 
change code, spawn compiles and hyperlink 
directly to the source of error quickly and efficient 
ly. Features point & click source code navigation 
and automatic generation of function call trees - 

List: $299 Ours: $259 



FAKcttcm f: 6005-0003 


Introducing the Lc 
SmartSuifce 32-Bit 
Bundle lor OS/2! 

by Lotus Development Corp. 

Lotus' new SmartSuitc for OS/2 is the only com¬ 
plete 32-bil solution for OS/2 desktops. For a fim 
Ited lime, when you buy SmaitSulte for OS/2 or a 
Smart Sufic for OS/2 Upgrade*, you'll get OS/2 2-1 
FREE. Act now to take advantage of this special Introductory offer, while 
supplies last! 

List: $795 Ours: $599 
Upgrade*: List: $595 Ours: $319 

FA Xcetem #: 4000-0027 





Window Washer v2,0 

by One Up Corporation 

The latest version of the best-selling 32-hit 
screen saver for OS/2, with full system pass¬ 
word security and the most complete moni¬ 
tor burn-tn protection available today. 
Version 2.0 features many exciting animated 
effects, digital video and audio [plays CD s. 
MIDI or WAV files with program effects]. Also 
utilizes TtF, GIF. BMP. Sl PCX backgrounds. 

List: $39.95 Ours: $35 

FAXr.ifra #: 6005-0001 


SQL Objects++™ 
Database Class Library 

by Graphical Software 
Interfaces, Inc. 

SQL Objects++ m Database Class Library Is a 
powerful collection of object-oriented database classes that provide direct 
access to SQL and non-SQL databases. Each class Is fully optimized to pro¬ 
vide fast access to your data. No other access library is designed to fully 
utilize your OS/2 environment. 

List: $699 Ours: $499 

FAXfCifm#: 1010-2601 
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Open Shutter vl. 11 

by One Up Corporation 

Our easy-to-use screen capture process 
allows you to select any rectangular area, 
window, or entire desktop, and capture 
with a single user-defined keystroke or 
mouse click. Rotate, change colors, 
stretch/compress and then preview your 
modifications. Outpui to printer, clipboard, or soft copy in a variety of 
formats (BMP. ICO, TIFF, GIF, IMG, metafile, MacPaint). 

List: $69.95 Ours: $59 
FAXceura #: 6005 0002 



Gpf 2,1 Professional with 
Developer's Toolkit 

by Gpf Systems, Inc, 

WYSIWYG GUI design environment. Full 
support for OS/2 2.x, OS/2 l,3.x* and 
MS Windows 3.0 and 3.1. Point and 
click Lo design a CUA ‘91 compliant GUI 
with no run time Interpreter or royalties. 

Gpf generates C or C++ source, includ¬ 
ing SQL for DB2/2, as well as Help 
source, and ail ancillary files (IFF/RTF. RC. h, DEF, MAK, etc.). All naviga¬ 
tion and even user custom logic is added from within Gpf, 

List: $1440 Ours: $1269 
FAXtftfffl #: 3582-0002 



Ami Pro 3.0 for OS/2 

by Lotus Development Corp. 

OS/2 users now have a native, 32-bit version of the 
award-winning Amt Pro 3.0 for Windows. Written from 
the ground up for OS/2, the new version of Ami Pro 
provides the highest level of word processing, net¬ 
working and development power among OS/2 word 
processors. 




GUARANTEED BEST PRICES! 

(Call for details) 

To order call: 800-445-7899 

Corporate (CORSOFT): 800 422-6507 
FAX: 908 389-9227 
International: 908 389-9228 
Customer Service: 389-9229 

For more information on the products 
featured on these pages caJI— 

FAXviera®: (201) 762-1378 


Ruwjji/u/i 


List: $495 
Upgrade: List: $129 

TAXcetem #: 4000-0011 


Ours: $369 
Ours: $ 99 


Shrewsbury, NJ 077Q2 




* All prices are subject to change without notice. 
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Object-Oriented 


This article is an introduction to the SOMObjects Developer Toolkit 2.0 for OS/2 2.0 or 2. T This major new 
release of the product, often described simply as "SOM ," includes not only major upgrades on the SOM kernel 
itself but also includes several important frameworks that provide new development opportunities for the 
designer and implementor of SOM objects, by Roger sessions, nurcan coskun, and Charles erickson 


SOMObjects Developer Toolkit: 
An Overview 




Roger Sessions 



Nurcan Coskun 



Charles Erickson 


r he SOMObjects Toolkit is a product 
designed for programmers involved in 
object-oriented programming. The Toolk¬ 
it includes both the SOM Kernel and the SOM 
Frameworks. The SOM Kernel provides a mecha¬ 
nism for writing language-independent object-ori¬ 
ented classes. By language-independent, we mean 
that the class consumer can use a different lan¬ 
guage than that used by the class implementor, as 
long as both consumer and implementor lan¬ 
guages supports SOM bindings. The SOM Frame¬ 
works greatly decrease the programming effort 
required to give those classes basic functionalities 
such as persistence and object distribution, 

in this article, we'll introduce you to the use of 
the SOM Kernel and SOM compiler. These two 
components provide the basic functionality need¬ 
ed to create classes. Wei! develop a complete 
example and give you all the information you'll 
need to compile and run each example. We 
assume only that you have installed the toolkit 
according to the installation directions. This will 
allow you to use the examples as the basis for your 
own programming efforts. 

INTRODUCTION TO THE 
SOMOBJECTS TOOLKIT 

The process of creating a SOM class is summa¬ 
rized in Figure 1, The programmer defines a class 
in a language known as the Interface Definition 
Language, or TDL. This definition is placed in a file 
typically named with the extension ML. The SOM 
compiler is run against this IDL file and three files 


are generated. The first is a header file used for 
class implementation code, named with the exten¬ 
sion ih. The second, a header file used by clients, is 
named with the extension h. The third is a method 
template file containing C code skeletons for each 
method described in the class definition, named 
with the extension c. These skeletons are filled in 
by the programmer. 

Programmers who used the first version of SOM 
will notice right away that the class definition lan¬ 
guage has changed. Classes used to be defined with 
a language known as OIDL, or Object Interface Def¬ 
inition Language. Although OIDL is still supported, 
we are encouraging people to port their code to the 
IDL syntax for several reasons. Perhaps the most 
important is that the IDL syntax used to define 
classes and the associated C bindings has been 
accepted as an industry standard. The standard has 
been worked out through the Object Management 
Group (OMG) and their CORBA specification. 
Another reason for moving to IDL is that it allows 
use of new SOM Frameworks including Distributed 
SOM orDSOM. 

As changes are made to the IDL file, the SOM 
compiler must be rerun. The .ih and .h files are 
regenerated and the jz file modified to add new 
skeletons for any newly defined methods. Exist¬ 
ing method code is left untouched. 

BASIC PROGRAMMING EXAMPLE 

Let's start by looking at the definition, implemen¬ 
tation, and use of a simple SOM class: an appoint¬ 
ment. An object of the appointment class knows 
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about a particular appointment during the day. 
Appointments are characterized by a date, start¬ 
ing time, ending time, and subject. The subject is a 
description of the appointment's purpose, 

A high-level description of this class in class 
definition pseudocode is shown in Figure 2. 
Appointment is derived from SONObject, the default 
root class for all class derivations. We have indi¬ 
cated the direction of all parameters. The keyword 
in is used to indicate a parameter that is not updat¬ 
ed, All of our parameters are in. 

There are a series of relationships between cer¬ 
tain instance data and pairs of methods. For exam¬ 
ple, there are the instance data year and the two 
methods set_year() and get_year(). It is quite com¬ 
mon to have a particular piece of instance data 
associated with a set method, which sets the value, 
and a get method, which returns the value of the 
instance data. 

There is a shortcut to declaring an instance 
data, a set and a get method—declaring an 
attribute. If we see an attribute year, we can inter¬ 
pret this as declaring a data element year, and a set 
and a get method. By using attributes, we can sim¬ 
plify Figure 2. The new high-level description of 
appointment using attributes is shown in Figure 3. 

Appointment includes a method named buffer- 
ize(), We will follow a rule that says object imple¬ 
mentation and I/O should be kept separate. 
Another way of saying this is that objects should 
be separated from code that prints them out or 
reads them in. We use the method bufferizeO as a 
convenient way to request an Appointment object to 
return a formatted string information about its 
contents. The separation of object implementation 
from I/O will greatly simplify the use of several 
frameworks of the SOMObjects Toolkit. 

We also want Appointment to override certain 
methods inherited from SOHObject. The overriden 
methods are sontfhitO, the method invoked on an 
object when that object is first created, and 
somUninitO, the method invoked on an object when 
that object is destroyed. Updating Figure 3 to 
show overridden methods gives Figure 4. 

Notice that SOM has predeclared certain types. 
These types can be used in the declaration of 
attributes, return values for methods, and parame¬ 
ters of methods. The valid types are shown in Fig¬ 
ure 5. In this article, we use only short (which is 


class.idl Class Definition File 

1 


SDM Compiler 


t 

11 cl ass .c 
class, h 
class.ih 

▼ 

Method body lilted in by class implementor 

1 

C Compiler 

1 

Loader 


Figure 1 . Summary of the SOM process 



Figure 2 High-level description of Appointment class 


Template file for class implementation. 
Header file for client code. 

Header file for class.c 
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class: Appointment 
derived from: SOHObject 
attributes: short year 
short month 
short day 

short startiiigTijne 
short endingTime 
string subject 

methods: string bufferizetin string buffer) 
Figure 3 High-level description of Appointment class using attribute 


class: Appointment 
derived from: SOHObject 
attributes: short year 
short month 
short day 

short startingTime 
short endingTime 
string subject 

methods: string bufferizedn string buffer) 
overriden methods: somlnit 
somUninit 


Figure 4. High-level description of Appointment class using attributes and showing 
overridden methods 



Figure 5 L Valid IDL types 


equivalent to the C type short int), 
string (equivalent to the C type char*), 
and sequence (equivalent to a specific 
structure in C). 

The IDL file that defines the Appoint¬ 
ment class, appt.id, is shown in Figure 
6, Line numbers are given for ease of 
reference. It should be relatively easy 
to relate this back to the high level 
description shown in Figure 4, 

Let's go through the IDL file shown 
in Figure 6 line by line. 

Lines 01, 02, and 52 ensure that this 
file is compiled only once. This is simi¬ 
lar to the technique used in C++ to 
ensure that class definitions in that lan¬ 
guage are compiled only once (see Ses¬ 
sions, Class Construction in C and C++). 

Line 04 includes the IDL definition 
for the base class of this class. 

Line 06 declares Appointment to be an 
interface {or a class, for our purposes) 
and notes that the class is derived from 
SOHObject, Notice that the interface dec¬ 
laration encompasses lines 07-50, inclu¬ 
sive, as indicated by the brackets. 

Lines 12, 15, 18, 21, 24, 27, and 30 
declare the attributes for the class. Line 
08 declares the only method of the 
class. 

The implementation section of the 
class declaration begins at line 32 and 
ends at line 49 (again as indicated by 
brackets). This section contains infor¬ 
mation not considered part of the inter¬ 
face per se, but still necessary to the 
class declaration. Pragmatically, the 
implementation section contains any 
information that is an extension of the 
0MG CORBA standard. Notice that the 
implementation section is within the 
interface section. 

Within the implementation section, 
we see a dHname statement at line 34. 
The purpose of this is to tell SOM the 
name of the dll into which the object 
code for this class will be built. This 
information is used by SOM to locate 
and dynamically load class libraries. 

Also within the implementation sec¬ 
tion, we see a releaseorder section from 
lines 35-38. This section is designed to 
ensure that base classes can be modi¬ 
fied without forcing derived classes to 
be recompiled. We will not explain 


how this works technically, but the 
rules for implementing this section are: 
Whenever a method is added to the 
class, it is added to the release order. 
Methods should never be removed 
from the release order (even when 


removed from the class) and methods 
should never be moved within the 
release order (even when moved with¬ 
in the class). Notice that these rules 
apply to methods implied by attributes, 
{such as _get_year()} as well as explicit 
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01 #ifndef appt_idl 
02 #define appt.idl 
03 

04 #indude <somobj.icH> 

05 

06 interface Appointment : SOMObject 
07 { 

08 string bufferizeO; 

09 // Returns the external representation of the appointment 

10 // as a string. 

11 

12 attribute short year; 

13 // The year of the appointment. 

14 

15 attribute short month; 

16 // The month of the appointment. 

17 

18 attribute short day; 

19 // The day of the appointment. 

20 

21 attribute short start; 

22 // The starting time of the appointment. 

23 

24 attribute short end; 

25 // The ending time of the appointment. 

26 

27 attribute string subject; 

28 // The subject of the appointment. 

29 

30 attribute short apptld; 

31 

32 implementation { 

33 

34 dllname = "apptbk.dll"; 

35 releaseorder: bufferize,_get_year,.set.year, 

36 .get_month,.set.month,.get.day,.set.day, 

37 .get.start, .set.start, _get_end, .set.end, 

38 .get.subject,.set.subject, .get.apptld, .set.apptld; 

39 

40 // Method Modifiers 

41 somlnit: override; 

42 somUninit: override; 

43 

44 // Attribute Modifiers 

45 subject: noset; 

46 

47 // Instance data 

48 string bp; // buffer used by bufferize method 

49 >; 

50 }; 

51 

52 fendif /* appt.idl */ 

Figure 6. IDL definition for Appointment, appt.idl 
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Gary Slattery, Software Developer, Computer Associates 


u The best platform for 
DOS and Windows.” 

"I develop software applications for a living 
and I think OS/2® is a great way to do 
business.” A 32-bit, virtual memory operat¬ 
ing system, OS/2 is the ideal platform for 
developing your DOS, OS/2, Windows™ anti 
even host-based applications. 

With OS/2 you can boost the power of 
your favorite DOS and Windows tools, 


IBM and OS/2 are registered Iractemarks arid Workplace Shell C++. Common View. 

C and OS/2 Crash Protection are trademarks of International Business Machines 
Corporal ion. All other products are irademarks or registered trademarks ol their respective 
companies ©1993 l&M Corp. 


more 


plus take advantage of over 250 available 
OS/2 development tools and utilities. 
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It’s a productivity thing. 

“I use CA Realizer to prototype new 
graphical interfaces. I write code using 
CA C++™ and CommonView™ (integrated 
with IBM’s C Set/2™ compiler) 
while I compile in the 
background. And when 
designing reports or 
planning schedules, 

I use CA-RET” 

0S/2’s pre-emptive 
multitlireaded multitasking dynami¬ 
cally manages CPU time so you can run 
DOS, Windows and OS/2 apps 
concurrently in different sessions 
with maximum efficiency. That 
means you can edit in one win¬ 
dow, compile in another, link in a 
third and test in a fourth. With OS/2 Crash 
Protection,™ if one application goes down 
due to a bug, the rest you’re working on 
wont. “There’s no limit to what you can do 
with this system.... It’s definitely made me 
more productive.” 



The Development Platform of Choice 

* Enhanced development platform for DOS. Windows and 
OS/2 apps. 

* OS/2 Crash Protection for superior reliability. 

* Pre-emptive multitasking for increased productivity, 

* Virtual memory provides up to 512MB per session. 

* Flat memory model eliminates wrestling with segments, 

* Multiple virtual DOS machines for concurrent app 
testing, 

* Object-oriented Workplace Shell is easy and intuitive. 










The object-oriented 
user interface—the Workplace^^L 
Shell™ (WPS)—gives you easy control with 
direct manipulation of visual objects on 
your computer screen. And should you need 
assistance with anything, IBM’s Worldwide 
Developer Assistance Program is always there 
to help. 

“A developer s dream.” 
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for Technical Excellence 



With 0S/2’s 32-bit architecture, you can 
push your 386 and 486 hardware to the limit, 
and develop spectacular multimedia 
and enterprise-wide client-server 
applications. OS/2 lets you create 
the widest range of applications, 
for a variety of platforms, for 
almost any size computer. Here’s 
your chance to develop truly 
revolutionary 32-hit applications. With 
OS/2, now there’s nothing stopping you. 

To learn more, call 1 407 982-6408 
now, and get a free white paper on why OS/2 
is the ideal platform for your 
development efforts. 

Operate at a higher level. 


0SJ?, V8f*.on2.Q 
IBM Corporatkpn 




Use OS/2 to increase productivity of IX)S , Windows and 
OS/2 application development. 
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SOScope void SOMLINK _set_subject(Appointment *somSelf, Environment *ev, 
string subject) 

{ 

AppointmentData *somThis = AppointmentGetDataCsomSelf); 
AppointmentHethodDebug("Appointment"*"^set^subject ,f ); 

somIhis->subject = subject; 

} 

Figure 7. Default set method for attribute subject 


Idefine Appointment_Qass_Source 
lindude <appt,ih> 

SGMJJcope string SOMLINK bufferize(Appointment somSelf* Environment 

*ev) 

{ 

AppointmentData *somThis - AppointmentGetData(somSelf); 

AppointmentMethodDebug{ ,, Appointment% M bufferi 2 e"); 

return; 

> 

SQHJJcope void SOMLINK _set_subject{Appointment somSelf, Environment *ev, 

string subject) 

{ 

AppointmentData *somThis - AppointmentGetData(somSelf); 
AppointmentMethodDebugC 1 Appointment","_set subject"); 

} 

SOM Scope void SOMLINK somInit(Appointment somSelf) 

{ 

AppointmentData *somThis = AppointrnentGetData (somSelf); 
AppointmentMethodDebug{"Appointment","somlnit"); 
Appointment_parent_SOMObject_somInit(somSelf); 

} 

SOMJkope void SOMLINK somUninittAppointment somSelf) 

{ 

AppointmentData *somThis = AppointmentGetData(somSelf); 
AppointmentMethodDebugC 1 Appointment","somUninit"); 

Appointment parent SOMDbject_somUninit(somSelf); 

} 

Figure ft SOM Compiler generated c file from appt.idl 


methods (such as bufferizeO). 

The overrides are declared as shown 
in lines 41 and 42, Notice that parame¬ 
ters of overridden methods are not 
given here; they can be inferred from 
the IDL file describing the base class. 

Attributes can be modified, as 
shown in line 45. The only attribute 
modifier we use is noset. The keyword 
noset tells the SOM compiler that we 
don't want a set method automatically 
generated for this attribute. Instead, we 
want to write our own. We'd do this in 
a situation where the set method that 
would have been generated wouldn't 
be adequate for our purpose. The 
default set methods generated for string 
attributes are almost always inappro¬ 
priate and must be written by hand. 

We can see why it is best to hand 
code the set methods for string attribut¬ 
es if we look at what would have been 
generated for the set method had we 
not used noset. The default set method 
is shown in Figure 7. 

The default set in Figure 7 is rarely 
appropriate for any attribute that is 
essentially a pointer to something 
because it results in memory leakage. 
A better algorithm for a set involving a 
pointer looks like: 

* See if data member is already point¬ 
ing to something 

* If so, free what it is pointing at 

* Allocate memory for the new value 

* Copy the parameter to the newly 
allocated memory 

* Set the data member to the newly 
allocated memory 

By using the noset modifier in line 45 
of Figure 6, we reserve for ourselves 
the right to write our own set for the 
attribute subject. 

Having completed the definition of 
Appointment, we are ready to use the 
SOM compiler to generate a file con¬ 
taining method skeletons. The com¬ 
mand to accomplish this is: 

sc -sc appt 

where appt is the root name of the file 
containing the definition of Appointment, 
and the .idi extension is assumed. 

This command produces the ,c file 


shown in Figure 8. 

Our job is to take the skeleton file in 
Figure 8 and fill in the body of the 
methods. Notice that the default set 
and get methods do not appear in this 
file, although those identified by noset 


do appear. (The default set and get 
methods can be found in the SOM com¬ 
piler generated appt.ih file.) The filled- 
in skeleton file is shown in Figure 9, 
again with Line numbers added to facil¬ 
itate discussion. 
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mission 


Set your eyes on this: C Set- H- gives the Workplace Shell m 
quite a workout. 


CSet 


Get set for incredible 32-bit power. Get set for 
mission critical reliability. Get set for a range 
of advanced features. Get C Set++™ from IBM 
Programming Systems. C Set++ is the 
most complete object-oriented applica¬ 
tion development package you can buy 
for OS/2 ! 

C Set++ lets you create the most 
advanced, high-performance applica¬ 
tions imaginable. Its 32-bit C/C++ compiler lets 
you unleash all the power of OS/2, giving you 
industrial-strength code for your mission critical 
applications. It has an extraordinary code opti¬ 
mizer with a full set of options—even 
a switch to optimize for the new Pentium" 
processor. Plus there’s a full set of 
class libraries, including application C 


for the 


frameworks for PM, container classes and classes 
for multitasking, streams and more. 

There’s a whole set of other helpful features, 
like an interactive source level debugger. The 
unique Execution Trace Analyzer traces the exe¬ 
cution of a program, then graphically displays dia¬ 
grams of the analysis. You also get Workframe/2™ 
a language-independent tool that lets you 
customize your own environment. It’s adapt 
able and flexible— you can 
use any 16 and 32-bit DOS, 

Windows™ and OS/2 tools. 


With C SetH—h, it’s easier than ever to 
set your sights on success. To order or to 
find out more about OS/2 2.1 or C SetH—1-, 
call 1 800 3-IBM-OS2. In Canada, call 
1 800 465-7999, ext. 460. 

Operate at a higher levels 



IBM and OS/2 are registered trademarks and C Set + i . Workplace Shell. Workframe/2 and 
"Operate at a higher level" are trademarks of Internationa! Business Machines Corporation 
Pentium is a trademark of Intel Corporation Windows is a trademark of Microsoft Corp 
©1993 IBM Corp 
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Let's go through some of the more 
interesting lines in the filled-in skele¬ 
ton in Figure 9. First we see some 
bookkeeping lines (lines 1-2). These are 
added automatically by the SOM com¬ 
piler, and we will not discuss their pur¬ 
pose here. Similarly, the keywords 
SDM.Scope and SOHLINK are seen within the 
method declarations. They are typical¬ 
ly equated to static and the null string 
respectively. Therefore the line: 

SDM.Scope string SOMLINK buffering( 

can be thought of as being equivalent 
to: 

static string bufferize( 

We will not go into the reason for 
SDH .Scope and SOHLINK. 

The SOM compiler has automatical¬ 
ly supplied the correct parameters for 
each method, and that in addition to 
the parameters (if any) specified by the 
developer, SOM has supplied two 
implied parameters to every method 
(see, for example, line 5.) The first 
implied parameter is the receiving 
object, or what some authors describe 
as the target object. If you are not 
familiar with the concept of a target or 
receiving object, refer to Class Construc¬ 
tion in C and C+ (see the Bibliography). 
The second implied parameter is the 
Environment variable. Its primary pur¬ 
pose is to relay error conditions, a topic 
we will cover in a later article. 

Each method starts with some more 
bookkeeping lines such as 18 and 19, 
which we will not discuss here. If you 
need to declare local variables, they 
must precede the SOM supplied debug 
line. (For example, if the method 
somlnitQ needed to declare local vari¬ 
ables, they would go before line 34.) 

When a method needs to refer to a 
data element, even when the data ele¬ 
ment is implied by an attribute, we 
refer to it using an underscore, as in 
line 23: 

.subject = NULL; 


01 Idefine Appointment.CLass.Source 


02 #include <appt.ih> 


03 idefine BUF.SIZE 512 


04 



05 SQM.Scope string SOHLINK bufferize(Appointment somSelf, Environment *ev) 

1 06 { 



07 

AppointmentData *somThis = AppointmentGetDataCsomSelf); 


08 

AppointmentMethodDebug("Appointment","buffarize"); 


09 



10 

sprintf(_bp, "(7d) Date: Xd/Xd/Xd Start: 7,d End: 7 ( d\nSubject 

: Xs\n% 

11 

.apptld, .month, .day, .year, .start, ^end, .subject); 


12 

return(.bp); 


13 } 



14 



15 SQM.Scope void SOHLINK .set.subject( 


16 

Appointment somSelf, Environment *ev f string subject) 


17 { 



18 

AppointmentData *somThis = AppointmentGetData(somSelf); 


19 

AppointmentMethodDebugf"Appointment" /.set. subject"); 


20 



21 

if (.subject != NULL) { 


22 

SGMFree(.subject); 


23 

.subject = NULL; 


24 

} 


25 

if (subject -- NULL) return; 


26 

.subject = SOHMaHoc (strlen( subject)+1); 


27 

strcpy(.subject, subject); 


28 } 



29 



30 SDM.Scope void SOMLINK somInit( 


31 

Appointment somSelf) 


32 { 



33 

AppointmentData +somThis = AppointmentGetData(somSelf ); 


34 

AppointmentHethodDebugC"Appointment","somlnit"); 


35 



36 

Appointment.parent_SOMQbject_somInit(somSeif}; 


37 

.year = 0; 


38 

.month = 0; 


39 

.day - 0; 


40 

.start = 0; 


41 

.end = 0; 


42 

.subject = NULL; 


43 

.apptld = 0; 


44 

_bp = SOHMaHoc (BUF.SIZE); 


45 > 



46 



47 SDM.Scope void SOHLINK somUninitt 


48 

Appointment somSelf} 


49 { 



50 

AppointmentData *$omThis = AppointmentGetDatafsomSelf); 


51 

AppointmentHethodDebugf fl Appointment" , l, somUninit n ); 



Figure £ Filled in skeleton fife for appointment (continued on page 16) 
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Where 

This is the program, and the platform, BASIC was 
hoik for.Together,CA-REALIZER* 2.0 and OS/2* 2.1 
go above and beyond BASIC. 

With CA-REALIZER ,you get a visual program- 



CA-REAUZER 


is BASIC- 


mingtool that lets 
you develop visual 
applications with 
maximum impact. 

Its a structured superset of BASIC* extended to access 
objects and resources of both Windows™ and OS/2, 

You also get fully integrated Programmable Application 



Realize the full power of y our PC with OS/2, and you11 
never go bark to BASICs, 




Tools™ In short* its a developers dreamkit. 

CA-REALIZER eliminates the need for cumber- 
some SDKs, A totally new and improved visual Form Dev 
lets you edit multiple forms simultaneously, as well as 
adding items like scroll bars, spreadsheets, charts* 
animation and OLE objects. You can even import or 
export 1-2-3, Excel and Xhase files. 

With its pre-emptive multitasking, OS/2 makes 
CA-REALIZER a faster BASIC to work with, allowing 
you to move on while the system completes the previous 
job. And the applications you create can be compiled into 
stand-alone OS/2 programs you can distribute royalty- 
free with the run-time module that’s included,There’s 
even an award-winning report writer at no extra charge. 
Clearly, when it comes to BASIC, CA-REALIZER 
is anything but.To order or find out more about 
OS/2 2,1 or CA-REALIZER, call 1800 3-IBM-OS2* 

In Canada, call I 800465-7999. 

Operate at a higher level.” 

better. 


‘Or call Computer Associates at i SOQCALL-CAJ. IBM and OS/2 are registered trademarks and "Operate at a 
higher level" is a trademark of International Business Machines Corporation CA-REALIZER is a registered 
trademark of Computer Associates International. Inc, Windows is a trademark of Microsoft Corporal ion AN 
other products are trademarks or registered trademarks of their respective companies ©1993 IBM Carp. 
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Figure 9. Filled in skeleton file for Appointment (continued from page 14) 


01 lindude <appt.h> 

02 

03 main () 

04 { 

05 Appointment appt = AppointmentNewQ; 

06 Environment *ev = SOM.CreateLocalEnvironmentO; 

07 

08 _setjnonth(appt, ev, 12); 

09 __set_day(appt, ev, 05); 

10 __set_year(appt, ev, 1993); 

11 __set_start(appt, ev, 900); 

12 __set_end(appt, ev, 1100); 

13 __set_subject(appt, ev, “Product Planning"); 

14 _set_apptld(appt, ev, 1); 

15 

16 somPrintf("y,s\n", _bufferize(appt, ev)); 

17 _somFree(appt); 

18 SOMJ)estroyLocalEnvironment(ev); 

19 } 

Figure 10. Sample client program For Appointment class 


(1) Date: 12/5/1993 Start: 900 End: 1100 
Subject : Product Planning 

Figure 11. Output from the sample client program 


The underscore is used to indicate a 
data element of the target object of this 
method invocation. 

Memory allocation and deallocation 
uses the SOM-supplied functions SOM- 
HallocO and SOMFreeO (as seen in lines 
26 and 59) instead of their standard C 
counterparts. 

When you want to invoke the 
method defined for your base class, use 
the syntax MyQassName_parent_BaseCLass- 
Name.MethodName (parameters). A typical 
example of this is seen in line 36, where 
we have the somlnitQ method invoking 
its base classes somlnitQ. somlnitO is the 
method automatically invoked on an 
object when that object is first created. 
This is where one typically places any 
initialization code. 

The implementation file includes 
code for set.subjectQ, the set method 
for the attribute subject that we wanted 
to write ourselves via the noset modifi¬ 
er. The code for this method follows the 
algorithm given earlier for set methods 
involving pointer attributes. 

The initialization method, somlnitQ, 
sets up a newly instantiated Appointment 
object. Typically the first thing an 
implementation of somlnitQ does is to 
request the base class initialization, 
thus the invocation in line 36. The 
deinitialization method, somUninitQ, 
performs the reverse operation. 

A very simple client program that 
uses this class is shown in Figure 10. 
Notice that the client code has no 
knowledge of the Appointment class other 
that the interface section of the IDL. 

If we look at the client program 
shown in Figure 10, the first thing we 
see is the use of the SOM compiler gen¬ 
erated appt.h file. This file contains all 
of the information needed for a client 
to use a SOM class. 

The client declares an object of class 
Appointment and instantiates the object, 
as shown in line 5. The client invokes 
methods using an underscore preced¬ 
ing method names (as shown in line 17) 
and a double underscore preceding set 
or get methods for attributes (as shown 
in lines 8-14). 

All methods take as their first para¬ 


meter the receiving object. Most meth¬ 
ods take as their second parameter a 
pointer to an environment. (This will be 
discussed in a later article on error han¬ 
dling. For now, declare and allocate an 
environment using the syntax shown in 


line 6 and free the associated memory 
using the syntax shown in line 18.) 

Notice that not all methods take an 
environment pointer. Assuming you 
use standard IDL processing, any 
methods you declare will take an envi- 
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Developers: on your marks, get set—GUI 
With VX-Rexx™ WATCOM^s 
visual development environment 
(or OS/2" REXX, you’re on the fast 
track to creating applications that 
exploit the graphical user interface 
capabilities of OS/2 and the Workplace 

VX*REXX is an easy to use, powerful and fully 
integrated environment that combines a project 

management facility, visual designer and 
an interactive source-level debugger to 
deliver a very approachable and highly 
productive visual development environ¬ 
ment With the visual designer, you can graphically 
create OJA ’91 objects, quickly customize their 

get you 


wi ll reall y 

ce Shell™ I 



With the visual development environment of VX'RexX, 
it's all ays terns OIL 


properties, and easily attach REXX proce¬ 
dures to the objects. 

Since it’s based on IBM System Object 
Model (SOM) technology, the VX*Rexx 
environment is wide open. You can access 
all standard REXX API s including DB2/2. VX-Rkxx 
also lets you package applications as EXE files or PM 
macros. There’s support for multithreaded applica¬ 
tions. You can even include OS/2 style help and hints 
in your applications. 

To keep GUI-ing, WATCOM customer support 
delivers timely response by phone, fax, e-mail, 
CompuServe™ or the WATCOM bulletin board 


GUI-ing. 

OS/2 applications, VX’Rexx is the way ^ 
to GUI. To order or to find out more about OS/2 2.1 
or VX-Rkxx, call I 800 3-IBM-OS2. In Canada, 
call I 800 465-7999. 

Operate at a higher level. 


IBM and OS/2 are registered trademarks and "Operate at a higher level" and Workplace Shell are trademarks of 
Inter national Business Machines Corporation. WATCOM and VX*Rexx are trademarks of WATCOM International 
Corporation CompuServe is a trademark ol CompuServe Incorporated. © 1993 IBM Corp 
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ronment pointer. The only methods 
you are likely to run into that do not 
take an environment pointer are those 
declared in SOWObject and SDMCLass. 

We recommend, but do not require, 
that you use somPrintfO instead of 
printf (} for output as shown in line 16* 
This ensures that any character redirec¬ 
tion will be properly handled across the 
board. 

Good programming manners 
requires that you free all of your objects 
at the end of your program. This is 
accomplished through the use of 
Freed, as shown in line 18. Invoking 
.sonFreeO on an object automatically 
invokes the somUninitO method that we 
overrode for this class. The code for the 
overridden somUninitQ is shown starting 
at line 47 in Figure 9* 

Running this program gives the out¬ 
put shown in Figure 11* 

A MORE ADVANCED 
PROGRAMMING EXAMPLE 

Now that we've created the Appointment 
class, well use it as a basis for several 
other classes. Recall that objects of 
Appointment have a date, a starting time, 
an ending time, a subject, and an ID* 

In this section we will derive two 
new classes from Appointment. The first 
derived class is Meeting, which has a loca¬ 
tion in addition to what it inherits from 
Appointment. The second derived class, 
ConferenceCall, contains a phoneNumber. 

We will then create a constructed 
class, AppointmentBook, which will con¬ 
tain a sequence of Appointments. When 
we have a sequence of objects of class 
Appointment, by the rules of inheritance 
any of the sequence can be either an 
object of class Appointment or some class 
derived from Appointment* Since both 
ConferenceCall and Meeting are derived 
from Appointment, any of these three 
classes can be an element in the 
AppointmentBook. 

In the process of discussing Appoint- 
mentBook, we will discuss one of the tem¬ 
plate types shown in Figure 5, sequence. 

The IDL file defining the Meeting 
class, intg.idl, is shown in Figure 12. 
There are several points worth men- 


Figure 12 IDL fife for meeting: mtg.idL 

Honing about this file. This class is 
derived from Appointment (see line 6), 
whereas Appointment was derived from 
SOHObject, The object code for this class 
will be stored in the same DLL file as 
the code for Appointment, since they both 
use the same dll/iame clause (see line 13). 
The Meeting class adds one new attribute 
to those it inherits from Appointment; that 
attribute is location (see line 8)* One 
new attribute yields two implied meth¬ 
ods, a set and a get, both reflected in the 
release order (see line 14). Since this 
attribute is a string, we want to write 
our own set method, as we did for the 
string attributes of Appointment. Thus we 
declare the attribute noset (see line 22). 
Because we also want to override the 
bufferizeO method, we declare this 


method as override (see line 19). On line 
25 we have bp as the internal instance 
data to be used by the bufferize 
method* 

Figure 13 shows the method imple¬ 
mentation file for Meeting, As with 
Appointment, most of the file was auto¬ 
matically generated by the SOM com¬ 
piler with the command: 

sc -sc mtg 

The methods are very similar to the 
methods of Appointment, and require no 
further discussion. 

Figure 14 shows the IDL definition 
for the ConferenceCall class. The only 
substantive difference between this and 
the definition for Meeting is that now we 
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Everyone knows OS/2® gives you more applications to 
choose from. Now all you need is more space on your 
hard disk to load them all Stacker® for OS/2 & DOS is 
your answer. Stacker lets you quickly and safely double 
the capacity of your FAT hard disk, so you can take 
full advantage of OS/2—and virtually any DOS, 
Windows™ and OS/2 application you want. 

You can install Stacker in minutes* 
With Express or Custom Setup, you can 
automatically compress the data on the 
drive or customize the Stacker configu¬ 


ration to fit your needs, .And you can be sure your data is 
safe with the leader in disk expansion technology. In fact, 
over four million people worldw ide already trust their data 
to patented Stacker LZS™ compression technology. 





supports Boot ^ y 

world 


With Stacker, dmihling the capacity of your hard disk is 
as easy as pie. 


Stacker fully supports 
Manager and 
Dual Boot con¬ 
figurations* And 
there’s full support 
for 0S/2’s extended 
attributes, too. The Autoi Votect™ feature detects disk errors at 
boot-up and immediately protects your Stacker volume. 

Auto Recover)™ automatically repairs errors on the disk. And 
Stacker Optimizer™ even defragments a Stacker drive for 
optimal performance. 

With Stacker, you ('an get the most from your FAT hard drive* 

And with OS/2 on it, you can get the most from your computer* To 
order or to find out more about OS/2 2d or Stacker for OS/2 & DOS, 
call I 800 3-IRM-OS2, In Canada, call 1 800 445-7999. 

Operate at a higher leveL 
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IBM and OS/2 are registered trademarks and “Operate at a higher lever is a trademark of International Business Machines 
Corporation. Stac and Stacker are registered trademarks and LZS, AutoPnotect. AutoRec every and Stacker Optimizer are 
trademarks of Stae Electronics. Windows is a trademark ot Microsoft Corporation. © 1993 IBM Corp. 






















ttdefine Meeting.CLass.Source 
#inelude <mtg,ih> 

define BUF.SIZE 512 

SOM.Scope void SOMLINK _set_location(Meeting somSelf* Environment *ev, 

string location) 

{ 

MeetingData *somThi$ = MeetingGetDataCsomSelf); 

MeetingMethod Debug ("Meeting", ".set.location") ; 

if (.location != NULL) { 

SOMFree(.location); 
location = NULL; 

} 

if (location — NULL) return; 

.location * SGMMalloc{strlen(location)+l); 
strepyf.location, location); 


SOM.Scope void SOMLINK somlnitfMeeting somSelf) 

{ 

MeetingData *somThis = MeetingGetDatafsomSelf); 
MeetingMethodDebug ( 11 Meeting"," somlnit"); 

Meeting.parent.Appointment^somlnitf somSelf); 
.location = NULL; 

.bp = SOMMalloctBUF SIZE); 

> 

S0M_Scope void SDMLINK sonUninit(Meeting soniSelf) 

{ 

MeetingData *somThis = MeetingGetData(somSelf); 
MeetingMethodDebug("Meeting" f "somUninit"); 

if (.location != NULL) { 

SOMFreef.location); 
location = NULL; 

} 

SOMFree(.bp); 

Meeting^parent.Appointment.somUninit(somSelf); 


SOM.Scope string SOMLINK bufferize(Meeting somSelf, Environment *ev) 

{ 

string pbp; 

MeetingData *somThi$ - MeetingGetData(somSelf); 

MeetingMethodDebug("Meeting","bufferize"); 

pbp = Meeting.parent.Appointment_bufferize(somSelf, ev); 

_bp = SOHRealloeLbp, BUF.SIZE + strlen(pbp)); 
sprintf(_bp, "'/.sLocation : X$\n M , pbp, .location); 
return(.bp); 


Figure 13. C code for meeting: mtg. c 
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Tills just in. Applications Manager, best known as 
AM™ has just added OS/2* 2.1 support. We repeat, 
the flagship client/server application develop¬ 
ment software from Intelligent 
Environments is now available for 
OS/2 2.1 environments. 

For the latest-breaking devel¬ 
opments, wc take you to corporate 
America, where AM and OS/2 offer 
a tried and tested mechanism for building 32-bit, 
multitasking, line-of-business client/server appli¬ 
cations. AM’s visual programming environment 
streamlines the development and maintenance of 
mission-critical client/server applications by teams 
of programmers. And Static SQL support makes 
AM a real headliner. 

This recent news is becoming quite a feature 
story. By interfacing with 
MM PM/2, included 
with OS/2 2.1, 
programmers emj 
innovative team 
development 
capabilities 

like dynamically linked programming—simplifying 
reuse and maintenance of program code. DDE 
support allows programmers to paste information, 
including AM code, comments and yf/l/-gencrated 
documentation, into Windows™ 3.1 applications 
easily. And there’s also quicker screen interaction 
and improved productivity through support for 
0S/2’s new high-performance 32-bit graphics 
engine. 

With AM and OS/2, you’ll never again have to 
return to your regularly scheduled programming. 


acing with a —_ 

sl A 71 /f 

rVJ /|/f 




Use AM to develop your own highly rated network programs , 

news. 

To order or to find out more about OS/2 2.1 or 
AM, call 1 800 3-IBM-OS2. In Canada, call 
1 800 465-7999. 

Operate at a higher level.™ 


IBM and OS/2 are registered trademarks end “Operate at a higher level" is a trademark ol International 
Business Machines Corporation. AM is a trademark of Intelligent Environments, Inc. 2 HighwoOd Drive, 
Tewksbury, MAGI876 1 506 640-1060or 1 800 669-2797 Windows is a trademark of Microsoft 
Corporation © 1993 IBM Corp, 
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Figure ML Cortfere/ice ca// definition: ccall.ldL 


^define Con ferenceCaH.CLass .Source 
#include <ccall.ih> 

idefine BUFJI2E 512 

SOHJicope void 3QMLINK _set_phoneNu(nber{ConferenceCaIl somSelf, 

Environment *eu f string phoneNumber) 

{ 

ConfereneeCallData *somThis = ConferenceCaUCetData(sornSelf); 
ConferenceCalIHethodDebug( ,1 ConferenceCdn ,, > ,, _set_phoneNumber n ); 

if(.phoneNumber != NULL){ 

SQMFree(.phoneNumber); 
phoneNumber - NULL; 

> 

if(phoneNumber “ NULL) return; 

_phon eN umber = SOHHaHo c (st rlen (phon eN umbe r)+1); 
strcpyLphoneNumber, phoneNumber); 

Figure 15. Conference call implementation (continued on page 24} 
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} 

SQM_$cope void SOMLINK somInit(ConferenceCaIl somSelf) 

{ 

ConferenceCallData *somThis = ConferenceCallGetData(somSelf); 
ConferenceCaHMethodDebug("ConferenceCaH" /somlnit 1 '); 

Conf ereneeCall^ia rent Jppointment.somlnitfsoEnSelf); 
^phoneNumber - NULL; 

_bp « $OMMailoc(BUF„SIZE); 


SOM.Scope void SOMLINK somUninitfConferenceCall somSelf) 

{ 

ConferenceCallData *somThis = ConferenceCaXLGetData(somSelf); 

Conf erenceCallMethodDebugC^Conf erenceCaH", "somUninit 11 ); 

if(_phoneNumber != NULL){ 

SDMFree(_phoneNumber); 

^phoneNumber = NULL; 

} 

ConferenceCaH_parent^Appointment_somUninit(sorriSelf); 

> 

S0M_Scope string SOMLINK bufferize{ConferenceCall somSelf, Environment 
*ev) 

{ 

string pbp; 

ConferenceCallData *somThis - ConferenceCallGetData(somSelf); 

ConferercceCallflethodDebug("ConferenceCalT', "bufferize"); 

pbp = ConferenceCall^parentJppointmentJ>ufferize(somSelf, ev); 

_bp = SQMReallocLbp, BUF.SIZE + strlen(pbp)); 
sprintf(_bp, "XsPhone Number: XsVi", pbp, _pfioneltaber); 
return(_bp); 


Figure 15 Conference call implementation (continued from page 22) 


add a phoneNumber attribute instead of a 
location attribute. 

Figure 15 shows the ConferenceCali 
implementation. This closely parallels 
the implementation of Meeting, 

Next we look at the definition of 
AppointmentBook. As we discussed, 
AppointmentBook can take a number of 
appointments, any one of which can be 
either an Appointment, a Meeting, or a Con- 
ferenceCall. Actually, our system is set 
using Appointment as a kind of general 
base class, and we assume actual 
instantiations will be either Meeting or 
ConferenceCall. 

The definition of AppointmentBook is 
shown in Figure 16. There are two new 
syntactic constructions we have not 
seen before: const and sequence. The const 
construction allows us to define a con¬ 
stant value. The sequence allows us to 
define a simple collection of items. 

The sequence is basically a C struc¬ 
ture containing three elements. One of 
the elements is a pointer to a buffer 
containing an array. Unless the 
sequence is of a simple type (such as 
short or long), the nth item of the 
array is a pointer to the nth thing in 
the sequence. The second element in 
the structure is the number of items in 
the array and the third is the size of 
the array. The size of the array minus 
the number of elements already in the 
array tells us the number of empty 
slots in the sequence. 

SOM automatically defines a set of 
macros that make it easier to manage 
sequences. They are: 

* sequenceLength(sequence), which 
returns the length of a sequence 

* sequenceMaximijm(sequence), which 
returns the size of the array, 

* sequenceElement(sequence,n), which 
returns the nth element of the 
array. 

Since you will do most of your 
sequence access using these macros, the 
only sequence element you really need 
to know about is sequence.^buffer, a 
pointer to the array containing the 
pointers to the sequence items. 

As you can see from Figure 16, 
AppointmentBook defines four methods. 


addAppointmentQ takes an Appointment and 
adds it to the AppointmentBook. getDaysAp- 
pointmentsO takes information about a 
particular date and returns a sequence 
of all the Appointments that occur on that 
date. Note that the sequence this 
method returns Is a subset of the 
sequence attribute the AppointmentBook 
uses to internally manage its Appoint¬ 
ments. 

The last method is deleteAppoint- 
mentO. You can delete an appointment 
by invoking delete Appointment (), passing 


in the ID of the appointment to be 
deleted. The Appointment ID is actually a 
short integer that is one of the data ele¬ 
ments in Appointment. We have not 
talked about it much since its only pur¬ 
pose is to support the deleteAppointmentQ 
method. 

In our implementation, shown in 
Figure 17, AppointmentBook is responsible 
for assigning IDs to Appointments. It does 
this by starting with zero and Incre¬ 
menting the ID of each Appointment as it 
adds It. Notice that the AppointmentBook 
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Figure 16. AppointmentBook definition: apptbook.idl {continued on page 28} 


also contains a short attribute named 
apptld that keeps track of the last 
assigned Appointment ID, 

The first method in the implemen¬ 
tation file is add Appointment(). It is 
passed an Appointment, updates the ID 
of the Appointment, and then adds the 
Appointment to the appointments sequence. 
The only difficult part of adding the 
Appointment to the sequence is dealing 
with a situation in which the sequence 
is already filled. In this case, we reallo¬ 
cate the buffer size to be large enough 
for an additional APPOINTHENTS.INCR 
number of appointments and reset the 
sequenceMajdjnum. 

The next method in the implementa¬ 
tion is getDaysAppointmentsO, which starts 
by allocating a sequence large enough 
to hold all the appointments in a given 
day. It then checks each element of the 
appointments sequence and, if the date of 
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// Delete the given appointment from the book, 

attribute short apptld; 

// Appointment book id generator, 

implementation { 

dUname - "apptbk.dH"; 

r elea seo rd e r: add A ppoin tment,getDa y s A ppointme n ts, 
deleteAppointment, 

_get_appointments,_set_appointments , 
_get_apptld,_set_apptld; 

// Method Modifiers 
somlnit; override; 
somUninit: override; 

// Instance data 

sequence< Appointment> day sAppointments; 

>; 

h 


fendif /* apptbook_idl */ 


Figure 16 , hppointwentBook definition: apptbook.idL (continued from page 27} 


fdefine AppointmentBook_CXass_Source 
tin dude <appt.h> 
finclude <apptbook.ih> 

SDM.Scope short SOHLINK addAppointment( 

AppointmentBook somSelf, Environment *ev, Appointment nevAppointment) 

{ 

AppointmentBookData *somThis = AppointmentBookGetData(somSelf); 

A p poin tmen tB o o k M et h od Debug (" A pp oin tme ntB oak "/add A ppoi n tm en t p> ); 

/* Generate an id for the neuAppointment. 

---- */ 

_apptld++; 

Appointment__set_apptId(new A ppointment, ev, _apptld); 

/* Insert neuAppointment into the book. 

---— */ 

if (sequenceLength(_appointments) == sequenceNaximum(_appointments)) { 
sequenceMaxiinum(.appointments) += APP0INTMENT5JENCR; 

^appointments,.buffer - (Appointment *) 

SOMRealloc(_appointments..buffer J 
sizeof(Appointment) * sequenceHaximum( appointments)); 

} 

sequenceElement(_appointments, sequenceLength(_appointment$)) = 
neuAppointment; 

sequenceLength{.appointments)++; 
return( apptld); 

> 


Figure 17. AppointmentBook implementation (continued on page 30) 
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SQH.Scope _IDL_SEQUENCE_Appointment SOMUNK getDaysAppointments{ 
AppointmentBook somSelf, Environment *ev, 
short year, short month, short day) 

{ 

AppointmentBookData *somThis = AppointmentBookGetData(somSelf); 
int i; 

Appointment appt; 

AppointmentBookHethodDebug (" A ppointmentBook t! , ”getDay sAppointments 11 ); 

/* Allocate the returned buffer. 

----*/ 

.daysAppointments..buffer = (Appointment *) 

SOHRealloc(.day sAppointments..buffer, 

sizeof{Appointment) * sequenceLength(.appointments)); 
sequenceMaKimum{.daysAppointments) = sequenceLength(_appointments); 
sequencelength(.daysAppointments) - 0; 

/* Fill in the sequnece with the days appointments. 

---™-—..—-*/ 

for (i= 0; i< sequenceLength(_appointments}; i++) { 
appt s sequenceElementLappointments, i); 
if ((..getear(appt, ev) == year) M 
(__get_month(appt, ev) == month) && 

{__get_day(appt, ev) == day)) { 

sequenceElement(.daysAppointments,sequenceLength(_daysAppointments)) - 
appt; 

sequenceLength(.day s Appointments)++; 

} 

} 

return(.daysAppointments); 


SDM.Scope void SOMLINK deleteAppointment( 

AppointmentBook somSelf, Environment tev, short appointmentNumber) 

{ 

AppointmentBookData tsomThis = AppointmentBookGetData(somSelf); 
short i, j; 

Appointment appt; 

AppointmentBookHetbodDebugC” AppointmentBook V'deleteAppointment 1 ’); 

for (i=0; i< .appointments..length; i++) { 
appt - sequenceElementLappointments, i); 
if (Appointment..get.apptld(appt, ev) -= appointmentNumber) { 
— sequenceLength(.appointments); 

SOKFreet.appointments..bufferUie); 
for (j=i; j<sequenceLength(_appointments); j++) { 
sequenceElement{.appointments, j) - 
sequenceElementLappointments, j+1); 

> 

return; 

} 

} 


SDK Scope void 5QMLINK somInit(AppointmentBook somSelf) 

{ 

AppointmentBookData *somThis = AppointmentBookGetData(somSelf); 
AppointmentBookMethodDebug{ "AppointmentBook", 11 somlnit 11 ); 


Figure 17. AppointmentBook implementation (continued on page 31) 
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linelude <som.h> 

#include <appt.h> 

#include <mtg,h> 

♦include <ccall.h> 

#include <apptbook.h> 

fifdef „DHC„ 

♦pragma linkage 
(SOHInitHodule, system) 
iendif 

SOMEXTERN void SDMLINK SOHInitHodule 
(long majorVersion, 
long minorVersion) 

{ 

AppointmentMevCLass(0,0); 
MeetingNewCLass(0,0); 
ConferenceCaHNevQass(0,O); 
AppointmentBookNewQass(O } 0); 

} 

Figure 17. AppointmentBook implementation (continued from page 30) Figure 18 L initmd, c 


XppointnentBook_parent_SOMObject_somInit(somSelf); 
.apptld - 0; 

.appointments,.buffer = (Appointment *) 
SDMHaIloc{sizeof(Appointment) * APPOINTKENTS.INCR); 
sequenceMaximumf.appointments) - APP0INTHENTS.INCR; 
sequencelength(_appointments} 3 0; 

.daysAppointments,.buffer - (Appointment *) 
SSHMaHoc(sizeof(Appointment) * APPQINTHENTS.INCR); 


SDH.Scope void SOMLINK somUninit(AppointmentBook somSelf) 

{ 

AppointmentBookData *somThis “ AppointmentBookGetData(somSelf); 
int i; 

AppointmentBookHethodDebug( “AppointmentBook^, "somUninit "); 

for (i=0; KsequenceLength(.appointments); i++) { 

SOtfFree(sequenceElement( a ppointments, i)); 

} 

SOHFree(_appointments.^buffer ); 

SOMFree(.daysAppointments..buffer); 

AppointmentBook_parent_SOMObject_somUninit(somSelf); 


the Appointment matches the requested 
date, copies it into the sequence it will 
return. 

The next method is delete Appoint- 
ment(). We delete by appointment ID. 
The method looks through the appoint¬ 
ments, searching for one whose ID 
matches the parameter. When found, it 
is deleted from the sequence and the 
other elements of the sequence are 
pushed together to remove blank 
space. 

The next method is somlnitO, an 
override of one of the methods inherit¬ 
ed from SDHQbject. This method first 
invokes the somlnitO of its base class 
and then intializes its own instance 
data, .apptld is initially set to zero; 
newly added appointments, therefore, 
start with ID zero. Following this, the 
array portion of the appointment 
sequence maintained by this class are 
allocated to an initial size of APPOINT- 
MENTS.INCR elements. 

The next method is sonUninitO, 
another override of one of the SOMObj ect 
methods. This goes through appointments 
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Iindude <appt.h> 

Iindude <apptbook.h> 

•include <mtg.b> 

Iindude <ccaH.h> 

iindude <stdio,h> 

Idefine HAX_LENGTK 80 
Idefine WAX_ByFFER_SXZE 1000 

/* Prints a message and reads a line into buffer. 

----— */ 

static void getLine(buffer, msg) 
char bufferUe; 
char *msg; 

{ 

int i,c; 
somPrintf(msg); 

for (1=0; i<(MAX_LENGTH-l) M (c=getchar()) 

!= EOF y c!- 'W; ++ij 
bufferllie = c; 
buf fertile = '\Q'; 


void setOpAppointment(Appointment appt) 

{ 

char inputUMAJLLENGTHe; 

Environment *ev = somGetQobalEnvironmentO; 

getLine(input, "Enter month > "); 

.^setjno nth (appt, ev, atoi{input)); 

getLine(input, "Enter day > "); 

._set_day(appt, ev, atoi(input)); 

getLine(input, "Enter year > "); 

_$et^year(appt, ev, atoi(input)); 

getLine (input, "Enter starting time > *'); 
_set.$tart(appt, ev, atoi{input)); 

getLine (input, "Enter ending time > 1# ); 
__set_end(appt, ev, atoi(input)); 

getLine(input, "Enter subject > *); 

__set_subject{appt, ev, input); 

} 

main () 

{ 

short id; 
short i; 

short day, month, year; 

Appointment appt; 

AppointmentBook appt Book = AppointmentBookNeuO; 

JDL_ S EQU EJtfCE^ A ppoin tmen t appt Lis t; 
char menuUMAX.LENGTHe; 
char inputURJUJ-ENGTHe; 
string buffer; 
string menuLine = 

"\nm(meeting) c(conference) r (remove) d(display) q(quit) > 
Environment *ev = somGetGlobalEnvironmentO; 
do{ 

/* Display the menu options and read the operation. 

- --- “ -----*/ 

Figure W. Client program (continued at right) 


getLine(me nu, menu Line); 
switch(menuU0e){ 

/* Set up a meeting. 

— -- */ 

case V: 

appt = MeetingftlewO; 

setupAppointment(appt); 

getLine(input, "Enter location > "); 

__set_location{appt, ev, input); 

id = .addAppointment(apptBook, ev, appt); 

somPrintf{ 

"Appointment id for this meeting is : ftd \n", id); 
break; 

/* Set up a conference call. 

---- v 

case V: 

appt = ConferenceCallNewO; 

setupAppointment(appt); 

getLine (input, "Enter phone number > ,T ); 

__set_phoneNumber(appt, ev, input); 

id = .addAppointment(apptBook, ev, appt); 

somPrintf( 

“Appointment id for this conference call is : 1A 

W\ 

id); 

break; 

/* Remove an appointment. 

---- */ 

case V: 

getLine{input, 11 Enter appointment id > ff ); 
id = atoi(input); 

.deleteAppointment(apptBook, ev, id); 
break; 

/* Display the appointments for a given day. 

' -----— */ 

case 'd': 

getLine(input, "Enter appointment month > "); 
month = atoi(input); 

getLine (in put, "Enter appointment day > [r ); 
day = atoi(input); 

getLineCinput, "Enter appointment year > *); 
year = atoi{input); 

apptList = ^getDaysAppointmentsfapptBook, ev, 
year, month, day); 

for (i=0; i< sequenceLength(apptList); i++) { 
buffer = _bufferize(sequenceElement{apptLLSt,i), ev); 
somP rintf (" W,s", buff e r); 

> 

break; 

/* Clean up and exit. 

--- */ 

case 'q': 
break; 

} 

} while (menuUOe != 'q'); 

_somFree(apptBook); 


Figure f9. Client program (continued from left) 
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sequence freeing each element and, 
finally, the buffer itself. It also frees the 
sequence buffer used to return a day's 
worth of appointments. 

The last piece of code needed to 
implement a class library is the SOMInit- 
Hodule procedure, one of which must be 
implemented for each class DLL. 
SQUnitHoduLe is called by SOM after it 
dynamically loads your DLL. This 
function is expected to initialize your 
class library* The SOHInitRodule proce¬ 
dure must call the dassname NewCLass 
procedure of each of the classes imple¬ 
mented in your DLL. Our SOKrutModule, 
shown in Figure 18, calls the NewCLass 
procedure of each of our appointment 
book classes. 

Figure 19 shows a client program 
working with an appointment book. 
The main program is a loop following 
the algorithm: 

set up appointment book; 

do { show them what they can do; 
ask what they want to do; 
if (they want to set up meeting) 
create meeting appointment; 
if (they want to set up conference 
call) create conference call; 

If (they want to delete an 
appointment) delete appointment; 

If (they want to display a days 
appointments) show days appoint¬ 
ments; 

} while (they are not done) 

The most interesting part of the 
code is the display of the day's 
appointments. We go through the 
sequence asking each element to 
bufferize itself, then print out the 
resulting buffer. Notice how this 
depends on a polymorphic resolution 
of the method bufferizeO. 

The make file that creates both the 
client program (named SAMPLE.EXE) 
and the class library (named APPT- 
BK.DLL) is shown in Figure 20. The 
make file ss designed to be easily adapt¬ 
ed to other SOM projects. 

Figure 21 shows the module 


definition file used to create the 
APPTBK.DIL 

Figure 22 shows the output from 
one run of the program. We add a 
meeting and a conference call, then dis¬ 


play all appointments for 9/17/1993. 
Notice the polymorphic resolution of 
bufferizeO, indicated by the fact that the 
first displays the location and the sec¬ 
ond the phone number. 
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■a 


QBJS = sample.obj 

TARGET = sample,exe 

OLLDBJS = appt.obj mtg.obj ccall.obj apptbaok.obj initmodobj 

DLL = apptbk 

CFLAGS s -Q+ -W3 -D__HIG_LB_ -Ti+ 

LDFLAGS = /packd /packc /exepack /align:16 /noi /m SCLDEBUG) /nol \ 
/PK:VIO /co 

SCFLAGS = ~p -u -sh;ih;c 

CC - icc 

LIBLIST * t(SQMB A$E)\lib\somtk os2386 

CQRBASTYLE - t(SOMBASE)\inelude\somcorba-bid 

$(TARGET): $(CQRBASTYLE) $(DLL).lib $(DBJS) 

link386 ${L0FLAGS) $(QBJS), $*, $*/m, $(LIBLXST) t(DLt).lib, nul 

$(DLL).dll: $(CORBASTYLE) S(DLLQBJS) $(DLL).def 

link386 ${L0FLAGS) ${DILQBJS), Ji/m, J(LIBLIST), t(DLL).def 

$(0LL).lib: $(DLL).dll 

implib /nologo t(DLL).def 

.SUFFIXES: ,c ,h ,idl .ih ,obj .esc 

.c.obj: 

$(CC) $(CFLAG5) -Ge- -c $< 

.csc.ih: 

sc $(SCFLAGS) I*.esc 

.idl.ih: 

sc $(SCFLAGS) $*.idl 

.csc.h: 

sc $(SCFLAGS) $*.csc 

.idl.h: 

sc $(SCFL AGS) $*ddL 

dean: 

-del som.ir *,obj *.dll *.lib *.exe *.rnap *,ih $(CLEANFILES) 
t(CORBASTYLE): 

§echo This program requires the CORBA-style C bindings 
flecho created using the somcorba command. 

©exit 1 

appt.ih: appt.idl 
appt.obj: appt.ih appt.c 
mtg.ih: mtg.idl 
mtg.obj: mtg.ih mtg.c 
ccall.ih: ccall.idl 
ccall.obj: ccall.ih ccall.c 

ap pt book.ih: a pptbook.idl 
apptbook.obj: apptbook.ih apptbook.c 
initmod.obj: appt.h mtg.h ccall.h apptbook.h 
sample.obj: sample.c appt.h mtg.h ccall.h apptbook.h 

$(CC) ${CFLAGS) -c $*,c 


Figure 20, Makefile 


>nul 2>ftl 




LIBRARY apptbk BUTIN STANCE 

DESCRIPTION 'Appointment Book 
Class library' 

FROTHDOE 

DATA MULTIPLE NQN5HARED 
LQADONCALL 

EXPORTS 

A pp oin tme n tCCLa s sD a ta 
A ppoin tme n t Qa ss Da ta 
A ppointmentN evCla ss 
A ppoin tme n t Boo k CQa ss Da ta 
A ppointme n t Boo k Qa s s D a ta 
A ppointmentBook Neydass 
Con f e r e n c eCallCCLa s s Data 
Con f e r e n c eCaHCLa ss Da ta 
Con f e r e n c eCallN ewQas s 
MeetingCCLassData 
HeetingClassData 
HeetingNewClass 


Figure 21. Module definition file 
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But don’t worry. It’s all in good clean fun. Because now there’s 
a fast, cost-effective way to create graphic, easy-to-use inter¬ 
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IS 


m(meeting) c(conference) r(remove) d(display) q(quit) > m 


Enter month > 09 

Enter day > 

Enter year > 

Enter starting time > 

Enter ending time > 

Enter subject > 

Enter location > 


17 

1993 

1015 

1100 

Marketing Meeting 
7D0G4 


Appointment id for this meeting is : 1 

m(meeting) c{conference) r(remove) cKdisplay) q(quit) > c 


Enter month > 
Enter day > 
Enter year > 
Enter starting time > 
Enter ending time > 
Enter subject > 
Enter phone number > 


09 

17 

1993 

0900 

1000 

Product Planning 
512 111 2222 


Appointment id for this conference call is : 2 

m(meeting) c(conference) r(remove) d(display) q(quit) > d 
Enter appointment month > 09 
Enter appointment day > 17 
Enter appointment year > 1993 

(1) Date; 9/17/1993 Start: 1015 End: 1100 

Subject : Marketing Meeting 

Location : 7D004 

(2) Date: 9/17/1993 Start: 900 End: 1QOO 

Subject : Product Planning 

Phone Number: 512 111 2222 

m(meeting) c{conference) r(remove) cKdisplay) q(quit) > q 


■■ 


Figure 22. Program output 
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A new generation of object-oriented database management systems, or ODBMS, meets the demands of com¬ 
pute-intensive applications such as engineering design (CAD, CASE, and so on), telecommunications, and com¬ 
plex document management. This article gives an overview of ODBMS and illustrates how existing applications 
can be migrated from OS/2 file-based storage to an ODBMS. by mohammed anwaruddin 


Migrating From File-Based 
to Object Database Storage 
On OS/2 


O bject-oriented database management sys¬ 
tems are becoming widely used with many 
applications and operating environments. 
In fact it is almost impossible to qualify the many 
types of applications for which object databases 
could have value. Early users have come from sev¬ 
eral key fields (primarily engineering design, 
telecommunications, and document management) 
but are now found in areas such as financial prod¬ 
ucts and process control reporting. In general, an 
object database may make sense for your applica¬ 
tion if some or all of the following criteria are met: 


■ Object-oriented databases integrate 
object-oriented language facilities 
with database capabilities such as 
persistence, concurrency, and integrity. 


1. Traditional DBMS technology has not been 
appropriate because of performance demands 
or programming complexity. 

2. The amount of information is large or complex 
enough that DBMS capabilities such as recov¬ 
ery/restart, transaction consistency, or nonstop 
operations are required. 

3. The application requires multiuser concurrent 
access to data at a finer granularity than that of 


an operating system file. 

The level of complexity of data-intensive appli¬ 
cations such as CAD, CASE, and Network Man¬ 
agement—and the data they manipulate—has 
grown beyond the capabilities of traditional data¬ 
base systems, which are record-oriented and limit¬ 
ed by a finite set of data types. 

Object-oriented languages are ideal for these 
applications because they offer extensible data- 
typing capability, which facilitates the storage of 
information not suitable for conventional databas¬ 
es. Through the object-oriented concept of inheri¬ 
tance, behavior and representation can be passed 
from one object to another. This allows code shar¬ 
ing among software modules and structure shar¬ 
ing among data objects. 

Object-oriented databases integrate these 
object-oriented language facilities with the data¬ 
base capabilities of persistence, concurrency, 
transactions, recovery, querying, versioning, and 
integrity. There are a number of approaches for 
integrating object-oriented capabilities into data¬ 
bases. One obvious approach is to extend an exist¬ 
ing object-oriented language with database capa¬ 
bilities. Integrating C++, for example, with these 
capabilities has several advantages: 

* C++ users can use the ODBMS with very little 
extra effort. 

* With a single type system, you can utilize the 
compile-time type-checking of C++ to provide 
type-checking for persistent as well as transient 
data, 

* You can use the full power of C++, including 
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virtual functions, inheritance, polymorphism, 
encapsulation, and parameterized types for 
application development. 

* It promotes reusability of code because the 
same code operates on either persistent or tran¬ 
sient data. More important, libraries developed 
for manipulating transient data can be used 
with persistent data without change. 

* No translation code is required to map the in¬ 
memory presentation of data to the disk-resi¬ 
dent representation, as is done in the file sys¬ 
tem storage paradigm. 

* It is easy to convert applications to use persis¬ 
tent objects. 

The example in this article, discussed in the fol¬ 
lowing section, focuses on many of the aforemen¬ 
tioned aspects of a C++ based ODBMS. 

MIGRATING AN EXISTING 
APPLICATION TO AN ODBMS 

The example we have chosen to illustrate the rela¬ 
tive ease of converting an existing application 
using an ODBMS is given using ObjectStore for 
OS/2 from Object Design, Inc It is based on a code 
sample from an simple application that maintains 
a database of phone calls. {ObjectStore for OS/2 is 
the data management component of this C++ 
application written with C Set ++ from IBM and 
the OS/2 environment.) This setup is diagrammed 
in Figure 1. 

The original database, maintained in a flat text 
file, consists of data representing the total number 
of phone calls (volume) based upon the area code 
(ac) and the long distance carrier (Id). The function 
of the program is to: 

* Read in the database and create a binary tree 
representation, 

* Read a line of input and update the correct 
node in the tree, and 

* Write the tree structure back out to the flat file 
database. 

The program consists of three modules— 
update, read, and write. Figure 2 shows the main 
program, which constructs the in-memory data 
structure, reads input from a file, updates the 
correct node, and writes the translated data 
structure back to the flat file database. The read 
module (Figure 3) reads in the flat file database 
and creates the binary tree structure. The write 


module (Figure 4) transforms the tree structure 
to the disk-resident representation and writes It 
back to the flat file database. Each node of the 
tree is an instance of the class node, defined in 
node.hh (Figure 5). 


CSet++ 

Application 


OBJECT STORE 


OS/2 


Figure 1. Component technology 

The original application (Figures 2-4) is self- 
explanatory to C++ developers and won't be elab¬ 
orated on here. 

When this program is converted to work with 
ObjectStore (Figure 6), the binary tree structure can 

An existing application can be 
extended to a full object-oriented 
database management system. 


be written directly to the ObjectStore database, 
thereby eliminating the need for the read and 
write modules. That is, the binary tree structure is 
made persistent. 

7WE MIGRATED APPLICATION 

Any application using ObjectStore functionality 
must first call the static member function object- 
store:initialize() (line 4 of Figure 6). To create a 
persistent object, the database in which the object 
is to be stored must be specified. Before a persis¬ 
tent object is created, therefore, the database must 
be opened by calling the static member function 
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tinclude <stdio.h> 

#indude "node.hh" 

extern node* read_graph (char *); 
extern node* write.graph (node *, char *); 

main (int, char **argv) 

{ 

node *root, *ac - ptr J *ld_ptr; 

FILE *fp; 

int ac, ld f volume; 

/*- l%ead in the flat file k create the binary tree --- */ 

root = read_graph (argvUle); 

/* - Read in the input k update the correct node in the tree -- */ 

fp = fopen (argvU2e, V); 

/* 

Core of the program* Walks a binary tree k updates 
an existing node in the tree. 

*/ 

while (fscanf(fp, "U Xd Xd'\ feac, Aid, ^volume) \= EOF) 

{ 

ac_ptr = root; 
uhile (ac^ptr->value != ac) 
ac.ptr = ac_ptr->sibling; 
ld_ptr = ac_ptr->child; 
while (ld_ptr->value Id) 
ld_ptr = ld_ptr~>sit>lLng; 
ld_ptr->volume += volume; 

} 

fclose (fp); 

/* - Destroy the tree 6 save the file -- */ 

write_graph (root* argvUle); 

} 


database: :open() (line 5 of Figure 6), With 
ObjectStore, every read from or write 
to persistently allocated memory must 
be within a transaction. The transaction 
macros have the form 

OS_BEGIN_TXN (identifier, exception**, 
transaction^pe) and 
DS_END_TKN (identifier) 

In Figure 6, all persistent reads and 
writes are within the transaction tl. 

An object that has been stored in 
persistent storage is retrieved in sub¬ 
sequent processes by looking up the 
topmost (or entry-point) object by 
name and then by navigating to the 
target object. Line 7 of Figure 6 
retrieves a pointer to the database 
root named root and line 8 returns a 
pointer to the entry point object asso¬ 
ciated with the specified root. The 
program core (that is, statements 
within the scope of the while clause) 
remains unchanged from the original 
in Figure L The database is closed at 
the end of the transaction by calling 
the member function db->close() (line 
10 of Figure 6). 

Thus, the additional lines of code 
required to make this an ObjectStore 
application consist of calls to: 

* Open the database, 

* Start a transaction, 

* Find the entry point for the node 
data structure, 

* End the transaction, and 

* Close the database. 

BENEFITS OF MIGRATION 

The original application consisting of 
Figures 2, 3, and 4 is made up of 40 
lines of C++ code. The migrated appli¬ 
cation, shown in Figure 6, contains only 
28 lines, a reduction of 30%. In addition 
to substantial savings in coding, an 
ODBMS adds multiuser concurrency to 
a single-user application, transaction 
consistency with restart/recovery, and 
database administration capabilities. 

After migrating your C++ applica¬ 
tion, you can address areas of improved 
functionality- For example, you might 
wish to maintain versions of objects and 


Figure 2, Original C++ main program 

have the capability to merge them 
together at a later date if needed. Bidi¬ 
rectional relationships and collections 
facilities can be added to improve appli¬ 
cation performance and reliability. 

Of course, object databases vary sig¬ 
nificantly in their functionality and per¬ 
formance. When evaluating them, keep 
the following considerations in mind: 

* Performance in your application 


environment 

* Ease of use and programming 

* Ease of migrating existing applica¬ 
tions 

* Stability and track record of the 
vendor. 

Since the migration example above 
was based on the ObjectStore ODBMS, 
we will address some specifics of this 
database. 
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•include Cstdio.hh> 

•include "node, hh 11 

node *read_graph(char* inf He) 

int ac, Id, volume; 

node *rootj *ac_ptr, *ld_ptr; 

FILE *fp - fopen {infile, V); 
ac_ptr = NULL; 

while (fscanf(fp, "'/.d 7.d Xd% &ac, £Ld, ^volume) f= EOF) 

{ /*--Create the area code level nodes-*/ 

if (ac.ptr -= NULL) { 
ac_ptr = new node(ac); 
root - ac^ptr; 

> 

else { 

ac_ptr = root; 

while ((ac_ptr->sibling != NULL) && (ac_ptrevalue *= ac)) 
ac_ptr = ac_ptr->sibling; 
if (ac_ptr->value ■= ac) { 

ac_ptr->sibling = new node(ac); 
ac^ptr = ac^ptr->sibling; 

> 

} 

/*-- Create the long distance carrier nodes — */ 

Id^ptr = ac_ptr->child; 
if (ld_ptr == NULL) { 
ld_ptr = new node(Id); 
ac^ptr->child = ld_ptr; 
ld_ptr->volume = volume; 

} 

else { 

while {(ld_ptr->sibling != NULL) kk (ld_ptr->value Id)) 
IxLptr = ld - ptr->sibling; 
if (ld_ptr->value != Id) { 
ld_ptr*>sibling = new node(ld); 
ld_ptr*>sibling*>volume - volume; 

} 

> 

} 

close (fp); 
return root; 

} 

Figure 1 Head the flat database file and create tree 


OBJECTSTORE 

ObjectStore is a second-generation 
object-oriented database management 
system. Second-generation object-ori¬ 
ented database systems are based on 
C++, which provides most of the mech¬ 


anisms needed to describe and manip¬ 
ulate persistent objects. Complete data¬ 
base functionality is obtained by addi¬ 
tional language and runtime features, 
ObjectStore databases can also be 
accessed by applications written in C. 


The product augments the language 
and runtime system to provide facili¬ 
ties for modeling objects and managing 
large sets of objects, including: 

* A collection facility (sets, lists, and 
so on), 

* Queries on collections, 

• Relationships between objects, and 

• Versioning of objects in support of 
groupware, 

ObjectStore provides a unified API to 
persistent and transient data, as well as 
traditional DBMS features such as per¬ 
sistence, transaction management, dis¬ 
tributed data access, and associative 
queries. It also supports the client/ 
server computation model, in which 
the server handles all access to Object- 
Store databases, including storage and 
retrieval of persistent data. The server 
is responsible for concurrency control 
and recovery; transactions involving 
more than one server are coordinated 
using the two-phase commit protocol. 

ObjectStore client libraries provide 
an interface between the user's appli¬ 
cation and the server. The client man¬ 
ages the logical view of data including 
collections, queries, versions, transac¬ 
tion management, memory manage¬ 
ment, and relationships among objects. 
The client environment includes the 
ObjectStore Cache Manager, which 
maintains a cache of objects accessed 
by all the client processes on a machine. 
(A single cache manager handles the 
caches of multiple applications,) 
ObjectStore can address a database 
larger than the address space of the 
operating system by dynamically 
assigning portions of address space to 
correspond to portions of the databases 
used by the application. It provides 
three programming interfaces: C and 
C++ library interfaces and an extended 
C++ that provides a tighter language 
integration to the query and relation¬ 
ship facilities, 

IBM and OBJECTSTORE 

In 1993, Object Design and IBM signed 
a multi-year strategic relationship for 
developing and using object database 
technology, with IBM purchasing an 
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equity interest in Object Design. The 
two companies have since initiated sev¬ 
eral joint development projects. IBM 
Programming Systems will incorporate 
ObjectStore in several commercial 
applications involving document man¬ 
agement, groupware, and software 
development. 

CONCLUSION 

Object-oriented database systems hold 
promise for applications that deal with 
large amounts of non-record oriented, 
complex data. These systems integrate 
object orientation with database capa¬ 
bilities, simplifying the modeling of 
real-world problems. 
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Figure 4. Write tree structure back to flat file 


class node { 
public: 
int value; 
int volume; 
node *sibling; 
node *child; 
node( int val) { 
value = val; 
volume = 0; 

sibling = child = NULL: 

} 

} 

Figure 5. Class definition file 
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#include <ostore/ostore*hh> /* 1. Objectstore include file */ 

#include <stdio.h> 
tinclude "node. Mi" 

database #db; /* 2. Objectstore declaration */ 

main (int, char **argv) 

{ 

database.root *db_root; /* 3, Objectstore declaration <7 

node *root, *ac_ptr, *ld_ptr; 

FILE *fp; 

int ac, Id, volume; 

/* -- Initialize Objectstore -- */ 

objectstore::initialize(); /* 4, Objectstore statement */ 

/* - Open the 00 database —- */ 

db - database::open(argvUle); /* 5* Objectstore statement */ 

- 'll 1 ' | ,| 

/* - Read in the input & update the correct node in the tree -- */ 

fp = fopen (argvU2e, "r"J; 

/* Core of the program. Walks a binary tree 4 updates 
an existing node in the tree. */ 

OS.BEGIN.TXN (tl, 0, transaction::update); /* 6. Objectstore start Transaction */ 

db.root = database.root::find("root", db); /* 7. Objectstore: find entry point */ 

root = (node *)db_root->get_value(); /* 8. Objectstore: Pointer to entry point */ 

while (fscanf(fp, "Kd '/.d ’/d", ftac, idd, ivolume) != EOF) 

{ 

ac_ptr s root; 

while {ac_ptr->ualue != ac) 

ac_ptr = ac_ptr->sibling; 

Id.ptr = ac_ptr->child; 
while (ld_ptr->value 1* Id) 

Id.ptr = ld_ptr->sibling; 
ld.ptr->volume += volume; 

> 

OS.END.TIN (tl); /* 9. Objectstore: end the transaction */ 

fdose (fp); 

db->dose(); /* 19. Objectstore: Close the ODBHS */ 

} 

Figure 6. Migrated main C++ program 
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"Wt BUILT THRU VERSIONS Of OUR APPLICATION TO RUN ON EIGHT PLATFORMS. 
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configuration management. 
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Software Configuration Management (SCM), Well 
help you automate manual processes and avoid the 
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tions can cause. 

You can skip the lost data, the bug fixes that don’t stay 
fixed, the builds that include outdated modules, 
overwritten code and the frantic midnight phone calls 
about wrong versions that somehow made their way 
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Instead of wasting time wrestling with your 
development environment, you can concentrate on 
building quality applications, regardless of what 
language, programmer workbench, methodology or 
operating system you’re using. 
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and the confidence to create good code, knowing 
you’ve got a complete audit trail to show where you’ve 
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the LAN. It’s a complete family of products, designed 
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development architectures and operating systems. 
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PVCS Version Manager, PVCS Configuration Builder, 
PVCS Production Gateway, PVCS Developer’s Toolkit 
and PVCS Reporter. 

Put the power of The PVCS Series to work 
for you. Call for a free demo disk, evaluation, or a 
copy of the whitepaper, “Software Configuration 
Management: Choosing The Correct Interface". 
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apply the power of PVCS 
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The authors'previous article on custom controls ("A Color-Full Example: Using Color In Control Design ," OS/2 
Developer, September/October 1993) discussed how to create a threaded control. This article shows how to uti¬ 
lize the control within a Workplace object, by chris Andrew, mark a. benge, and matt smith 

An Object of Many Colors: 

Using Custom Controls 
Within A Workplace Object 



Chris Andrew 



am 


m 

Mark A. Benge 



Matt Smith 


/ n our previous article, we presented a 
threaded control that could be used to pick 
colors similar to those within the color 
palette of the Workplace Shell. In this article, we 
will show you how to use this control within a 
Workplace Shell object in order to create a Work¬ 
place class that you can utilize. Source code can be 
found on the usual electronic bulletin boards and 
on CompuServe, as detailed in the References sec¬ 
tion. 

The color wheel control we developed will now 
be utilized within a Workplace Shell object class, 
namely a color palette. This class is meant to illus¬ 
trate some of the principles of object-oriented pro¬ 
gramming, such as inheriting behavior from a par¬ 
ent object class, while at the same time illustrating 
that there is nothing magical about object-oriented 
programming or the Workplace Shell when inte¬ 
grating your own controls or those of the system. 

The new color palette provides a replacement 
object class for the system-provided color palette, 
with some enhancements to the original design. It 
shows how you can write other derivatives of the 
system-provided WPPalette object class to create 
an icon, bitmap, or other application-defined 
palette. Once you have grasped the simple con¬ 
cepts behind Workplace Shell programming, you 
should have no trouble creating your own object 
classes. 

We will also package our Workplace Shell 
object class into another custom control that can be 
used in any application, not just within the con¬ 
fines of the Workplace Shell itself. 


A BRIEF INTRODUCTION TO 
OBJECT-ORIENTED PROGRAMMING 

Object-oriented programming is a powerful tech¬ 
nique that allows applications to be developed in 
separate encapsulated units that frequently corre¬ 
spond to real-world problems modeled within the 
software. Each unit is known as an object class, and 
the functions that can be performed by an instance 
of that class are known as methods of the class. 
The object class also defines a data structure, which 
only the methods are allowed to manipulate, that 
exists for every instance of the object class. 

In other words, an object is merely a data 
structure that is manipulated exclusively by a dis¬ 
crete set of functions associated and instanced 
with that object's class, like that shown in Figure 1. 
The definition of the data structure and the func¬ 
tions that operate upon it is provided by its object 
class. Functions that manipulate an object are 
known as its methods; the variables within the 
data structure are often referred to as instance 
variables. 

The creation of a new object involves little more 
than allocating and initializing a new data struc¬ 
ture to represent the state of that object. Since the 
format of the data structure is defined by the class, 
the method used to create a new object (sometimes 
known as a factory method or, in C++, as the con¬ 
structor) is always provided by the class. Similar¬ 
ly, the destruction of an object (the destructor in 
C++) amounts to the freeing of that data structure 
once all the system resources that it utilizes have 
been cleaned up properly. 
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The only other thing you need to understand 
about object-oriented programming is how the 
principle of inheritance works—that is, how an 
object class can be written that inherits behavior 
from another object class. In the explanation up to 
this point, we have mentioned that the state of an 
object is uniquely described by a data structure 
contained within it That data structure actually 
contains all the instance variables for all of the 
classes from which this object class is descended. 
Similarly, the object supports all the methods 
defined by all of the classes from which it is 
descended, in addition to whatever new methods 
it has defined. The key concept is that when an 
object class is defined it is able to add new meth¬ 
ods and override the existing methods defined by 
its parent classes. 

INVOKING A METHOD ON AN OBJECT 
DERIVED FROM TWO PARENT CLASSES 

Think of this in the same way as subclassing a 
window in PM. Obviously, after a window has 
been subclassed it still responds to the same PM 
messages it did before. However, there is no guar¬ 
antee it will respond in the same fashion to those 
messages. The subclass procedure is able to over¬ 
ride the processing of any message and can also 
add processing for new user defined messages. 

In PM there is no limit to the number of times a 
window can be subclassed, provided it is done 
properly. Each subclass is able to add or remove 
message processing from all previous subclasses 
of the window. It is also able to keep its own state 
variables for a window that has been subclassed in 
order to control its behavior. 

Object-oriented programming allows us to do 
exactly the same thing, but instead of adding or 
removing processing for a message we are modi¬ 
fying the behavior of a particular method of that 
object class. 

Now that we've briefly outlined the concepts 
of what happens behind the scenes in object-ori¬ 
ented programming, we can briefly discuss IBM's 
System Object Model and the way it has been used 
in OS/2 2.x. 

THE SYSTEM OBJECT MODEL (SOM) 

Most object-oriented programmers make use of an 
object-based programming language, such as C++ 


Unraveling the GreatSYS_DLLS - 0S2.INI 
File Mystery 

Something that has been a mystery to many OS/2 developers due to lack of 
documentation is how to register a custom public window class, thereby making 
your control public to all applications. Public window classes are only part of this 
mystery; we will discuss it along with other details concerning SYS.OLLS. 

There are 3 keynames defined for the SYS.DLLS application name; Load. Load¬ 
PerProcess, and LoadOneTime. Within the 0S2.INI file, the strings associated with 
these keynames are blank-delimited lists of DLLs that are loaded—and whose 
ordinal 1 (ordl) function is called—at certain times, depending upon which 
SYS.DLLS list the DLL name appears. The ordl function for a specific DLL is 
defined in the .DEF file, like that shown in Figure 2, used to build the DLL. If you 
want to make your control public, the ordl function would contain the WinRegis- 
terClass call, which implements the CS.PUBLIC class style illustrated in Figure 3; 
we will go into more detail on this later. 

For the Load keyname, the ordl function is called each time VinCreateMs- 
gQueue is called. Load is used if you need to do a thread-level initialization like 
setting a thread-level exception handler. Although it used to be the only option, 
with the advent of other loading options it is of limited usefulness. 

For the LoadPerProcess keyname, the ordl function is called for the first Vin- 
CreateMsgQueue in a process, LoadPerProcess can be used if you have, for exam¬ 
ple, a common heap. The first time your DLL is loaded, register your window 
classes and allocate a sharable heap; on all subsequent loads, you need only 
access the shared memory. 

For the LoadOneTime keyname, the ordl function is called once and only once, 
when PM is initialized by the shell. LoadOneTime can be used to register a public 
window class. 

Registering A Public Class. To register a public window class for your control, 
add your DLL to the LoadOneTijne list. Your DLL, in turn, will contain an ordl func¬ 
tion that performs the WinRegisterClass call, which uses the CS.PUBLIC style 
shown in figure 3. Remember, CS.PUBLIC is only valid when used within the shell 
process. Therefore, to make your control public, perform the following steps; 

1. Make a backup copy of your current 0S2.INI file. 

2. Add your DLL to the LoadOneTime list for SYS.DLLS in the 0S2.INI file. 

3. Shut down and reboot. 

We have included a sample application that shows how to add your DLL name 
to the SYS.DLLS LoadOneTime list. (Note that if CS.PUBLIC is used by any process 
other than the shell process, WinRegisterClass will fail.) 

Restrictions. The appname SYS.DLLS, and the keynames Load, LoadPerProcess, 
and LoadOneTime are ail case sensitive; you must be aware of the case sensitivity 
as shown in the sample application. Additionally, there is a 255 character limit 
per each keyname string. Finally, if you have modified the string for the LoadOne- 
Time keyname, you must reboot for your change to take effect. 
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Figure 1 . Invoking a method on an object 


or Smalltalk, to develop object-orient¬ 
ed applications. These languages nor¬ 
mally come with a large library of pre¬ 
defined object classes that can be used 
as a starting point for deriving new 
object classes. 

When the Workplace Shell for OS/2 
2.0 project was started, there were no 
object-oriented languages capable of 
generating native 32-bit code. Given 
the object-oriented user interface of the 
shell, it seemed likely that the shell 
would have to be developed without 
the benefit of any object-oriented pro¬ 
gramming structure beneath the cov¬ 
ers. 

Fortunately, the System Object 
Model (SOM) technology that was 
being experimented with in the IBM 
AIX environment came to the rescue. 
SOM is really just a protocol that 
allows object-oriented classes to be 
defined in any programming language, 
even a procedural language such as C. 


DESCRIPTION 'Your Controls DLL' 

EXPORTS 

yourOrdlFunction €1 

* 

* 

* 

Figure 2. Ordinal definition within definition file 


VinRegisterGLass ( (HAB)NULL, 
M YourPubHcQass M , 
(PFNWP)YourVindovProc, 
CS.PUBLIC, 
sizeof(ULONG) ♦ 
sizeof(PVOID)); 

Figure 3. Defining public class 


The elegance of SOM comes in its abili¬ 
ty to create a language-independent 
definition of the interfaces to a particu¬ 
lar object class, one that can then be 
used in any programming language. 
Thus it would be possible to develop 
an object-oriented application using 
SOM in which the object classes that 
comprised the application could be 
implemented in different languages. 

In OS/2 2.x, a SOM run-time sup¬ 
port DLL basically handles all the nas¬ 
ties of creating and destroying objects, 
making sure that the object classes con¬ 
form to SOM programming conven¬ 
tions. In the OS/2 2.x toolkit there is a 
SOM compiler that will take a lan¬ 
guage-independent definition of an 
object class (the .CSC file) and convert 
it into a set of skeleton functions and 
header files that can be used with IBM 
C Set/2, IBM C Set++, WATCOM 
C/C++32, Borland C++ for OS/2, or 
Zortech C++ for OS/2 compilers. 

WORKPLACE SHELL 
PROGRAMMING 

The Workplace Shell is implemented as 
a series of SOM object classes. The defi¬ 
nitions of these classes are shipped 
with the OS/2 2.x toolkit as a series of 


class definition files (.SC files in the 
\TooU<t21\SC subdirectory) and their cor¬ 
responding C syntax bindings (con¬ 
tained in .H files in the \Toolkt21\C\0S2H 
subdirectory). 

A common misconception is that 
SOM is used only with Workplace Shell 
programming. SOM is available for use 
with or without the Workplace Shell. It 
is important to note, however, that 
SOM (which comes with OS/2 2.x) 
does not yet provide any useful object 
class libraries of its own. It is really best 
used from another object-oriented pro¬ 
gramming language such as C++ that 
has its own set of ready-to-run class 
libraries and books full of sample pro¬ 
gramming techniques. 

Workplace Shell is run automatical¬ 
ly when the OS/2 operating system is 
started. The object classes that comprise 
the shell provide for the creation and 
destruction of persistent objects (objects 
that stick around even though they are 
invisible to the user) which can be 
stored as files or directories on the hard 
disk or, alternatively, stored in the 
OS2.1N1 file as binary data blocks. 

The Workplace Shell also uses the 
container and notebook controls to dis¬ 
play objects to the user as icons; the 
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Now there’s a faster, easier, more affordable way 
to test your applications* Introducing Workstation 
Interactive Test Tool (W ITT) 2*1, for OS/2® 2*0* An 
AD/Cycle product from IBM Programming Systems 

WITT does it all* Record, edit, playback and screen compare* 
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VSE and OS/400? 
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created WITT 2J to help y ou improve the 
quality of your applications. 
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Method 

Purpose 

wpSetupCeil 

This method allows the data contained within a particular cell of a palette object to be 
modified* Note that because the palette handles storage of the cell data automatically, 
any changes made to the cells of the palette are persistent* 

MpfiedraidCell 

Forces a particular cell within the palette to be redrawn. Usually used in conjunction with 
the wpSetupCeil method in order to allow the user to see changes in the palette as they are 
made* 

wpPaintCeH 

A palette subclass must override this method in order to display a graphical representation 
of the data contained within a given cell of the palette. 

wpQueryPalettelnfo 

Returns the current properties of the palette object, such as the number of rows and 
columns of cells and the size of the each cell element in pels. 

wpSetPalettelnfo 

This method may be called at any time to modify the number of cells within the palette or 
to set the dimensions of each cell displayed. Note that if the cells are of variable width or 
height, the maximum height and maximum width must be set using this method, or cell 
data could be clipped* 

vpEditCell 

When the user clicks on the Edit**, push button at the bottom of the palette or double clicks 
on one of the palette cells, this method is invoked to bring up a value editing dialogue. 

Once again, all subclasses of WPPallete ought to override this method and invoke a suitable 
dialogue. 

wpflueryPaletteHelp 

This method should be overridden to tell the palette which panel to display when the user 
requests help (by pressing the Help push button in the palette window). 

wpclsQueryEditString 

Returns the text displayed in the Edit..* push button in the palette view. 


Table f. Description of methods defined by WPPalette object class 


properties of those iconic objects are 
displayed in a settings notebook. In 
addition, the shell provides a set of 
defined method-based programming 
interfaces for the definition of the con¬ 
text menu, settings pages, object details 
to be displayed in Details view, and so 
on* 

One of the most important features 
of the Workplace Shell is that it is easily 
customized by the user, but still very 
extensible. Since even the system-pro¬ 
vided object classes can be modified to 
suit the purposes of the user, the shell 
is truly an open-ended application. 

To customize the Workplace Shell, 
you must write one or more SOM 
object classes, placing them within a 
DLL. You also have to register, using 
WbiRegisterObjectClass, those object class¬ 


es with the shell so they can become 
part of the shell's list of available object 
types. 

Because of the object-oriented 
design of the Workplace Shell, you 
don't have to get involved in the usual 
PM programming chores such as creat¬ 
ing a message queue, variable storage, 
initialization, or using advanced fea¬ 
tures such as the container control, 
notebook control, or drag-and-drop. 
That functionality has already been 
written into the Workplace Shell; the 
associated behavior is inherited by all 
object classes* The only thing you must 
do is write the new behavior of your 
object class. 

As illustrated in the following exam¬ 
ple, it is possible to create a new object 
class that is implemented by fewer than 


a dozen lines of C source code. All its 
basic behavior is automatically inherit¬ 
ed from its parent Workplace Shell 
object class. 

The Workplace Shell provides an 
object class called WPPalette that pro¬ 
vides nearly all the functionality 
required to implement our ColorPalette 
object class* All instances of WPPalette 
are capable of storing a variable num¬ 
ber of data blocks, known as cells. 
Whenever the value contained within a 
particular data block gets modified, the 
palette object automatically saves that 
change back to its persistent form* In 
other words, we don't have to worry 
about how or where to store the colors 
to be displayed by our palette* 

WPPalette also provides a view that 
shows a graphical representation of the 
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Figure 5. An instance of the CoforPaiette class opened in Palette view 



Figure 6 . Color picker dialogue containing color wheel custom control 



Figure 7. Celt data used within a color palette 


value of each data block. The palette 
manages the creation of the window, 
scrolling and positioning the cells to be 
displayed. The only code we have to 
write is a routine that displays the 
value contained by a given data block 
and tells the palette how much room is 
required to draw each particular cell 
(the cells can be of different sizes). The 
palette view, shown in Figure 5, allows 
the user to drag a value from a cell so it 
can be applied to another window and 
also to edit the value of a given cell 
within the palette. We will completely 
override the method that edits a cell, 
displaying our own dialogue. This dia¬ 
logue, shown in Figure 6, contains the 
color wheel custom control that lets the 
user pick a color. We will allow the 
existing drag-and-drop functionality to 
be handled by our parent object class, 
as it needs no modification. Table 1 
summarizes the purpose of the various 
new methods defined for VPPalette. 

In actuality, we will not be deriving 
our object class from the WPPalette class 
but rather from the system-provided 
VPColorPalette class. We wish to inherit 
as much function as possible from our 
parent class, and VPColorPalette is the 
closest match to our desired functional¬ 
ity. Don't believe that explanation? 
Okay, would you believe that we're 
just plain lazy? 

The UPColorPalette object class con¬ 
tains all the code we will need to han¬ 
dle dragging and dropping colors from 
our palette. Each cell within an instance 
of the WPColorPalette object class is actu¬ 
ally a PAINTPOT structure in Figure 7, The 
first element of the cell data must 
always be the CELL structure (contained 
in the wppalet.h header within the 
\ToolKt21 \C\0S2H subdirectory), which 
merely contains a field describing the 
size of the whole structure in bytes. The 
rest of the structure can contain any¬ 
thing (in this case, just an RGB value), 
but notice that each cell's data does not 
have to be the same size. 

Now that we have discussed the 
basic functionality of the system-pro¬ 
vided color palette, we can consider 
what methods we need to override in 
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Hints And Tips From Von Den Workplace Hackmeister 

(Or, Confessions Of A Workplace Junkie) 

• When developing a class, you may get tired of watching the Workplace Shell open all the 
windows you had open the last time. The automatic restart function can be disabled using 
the following options in your CONFIG.SYS file: 

SET RESTARTQBJECTS=ND 

• We all make mistakes in our code, but the Workplace Shell is frequently very forgiving of 
serious mistakes: its exception handler just carries on to the next method call. The trouble 
is that this can be a hindrance during the development of an object class, when you'd love 
to know where your code is malfunctioning. Setting the following environment variable in 
your CONFIG.SYS file will turn off the exception handler: 

SET SHELL E KEPTIQ N H A N DLE R=N 0 

Many people experience problems when trying to compile and test an object class DLL This is 
because the Workplace Shell loves to hang on to your object class DLL and keep it loaded 
until all instances of your object class have disappeared. There is, however, usually no need to 
reboot your system. The following hints can be helpful: 

• Register your object class only once. The shell remembers that you have registered it, so 
you waste time if your de-register and register every time you modify your DLL. 

• Create only one instance of your object class for testing purposes: put it in a folder that 
can be closed, so the usage count for your class DLL will be either one (if the object is vis¬ 
ible) or zero (if the folder containing it is closed). When the usage count for your DLL 
reaches zero, the shell will usually unload the DLL unless your object has class associa¬ 
tions to a filetype or file extension. 

• To ensure that the Workplace Shell unloads your DLL as quickly as possible, use the fol¬ 
lowing environment variable in your CONFIG.SYS file: 

SET OBJ ECTSN DDZETIM E=0 

• If these techniques aren't working for you, consider using a small program as a replace¬ 
ment for the Workplace Shell, such as the MYSHELL.EXE program provided with the 
source code. This allows you to start and stop the shell just like any other application. 
When it comes time to try another version of your DLL, just stop the shell, replace the DLL, 
and then restart the shell. 

• We recommend kernel debugging to debug your object class, as you will be better 
equipped to understand when and how your methods are called because you have sym¬ 
bolic information for both the Workplace Shell DLL (PMWP.DLL) and the SQM,DLL (hey, we 
titled this "confessions of a hacker,” didn't we?). 

• If you are planning to use the kernel debugger, you will probably want to use the external 
prefix and class prefix operators in your .CSC files when you define your object class. This 

(continued on page 54) 


our subclass, which well call Color- 
Palette. Since all object classes ought to 
identify themselves with a unique icon 
and also name themselves so the user 
can easily distinguish which category 
of object he or she is dealing with, it is 
advisable to override both the wpcls- 
QuerylconOata and wpclsQueryTitle meta- 
class methods when creating a new 
Workplace Shell object class. 

Also, the wpclsInitOata method has 
been overridden, so we are guaranteed 
to have registered the color wheel con¬ 
trol on the Workplace Shell process 
using the yinRegisterdass API. This is 
done because the wpdsInitData method, 
called only once when the class is 
loaded, is an ideal place to perform 
one-time initialization and window 
class registration. Otherwise, there is no 
real need to override any of the other 
standard Workplace Shell methods and 
we can concentrate on the palette meth¬ 
ods described in Table 1. 

For a start, we wish to override the 
wpEditCeH method, so our object class 
will exercise the color wheel control 
created in our previous article. Over¬ 
riding this method will merely load up 
our ColorPickingOialog using VinUadDlg if 
it hasn't been previously loaded. The 
user will then be able to modify colors 
in the palette using the color wheel 
control. Notice that the ColorPickingDia- 
log is non-modal, providing the easiest 
way for the user to change values of 
multiple elements of the palette very 
quickly. The user Is free to choose 
another palette cell to be edited while 
leaving the ColorPickingOialog displayed. 

In addition, we are going to over¬ 
ride the wpPaintCell method to demon¬ 
strate how to draw the cell data. This 
isn't strictly necessary, since our parent 
class yPColorPalette already draws each 
PAINTPQT as a circular splotch of color. It 
is, however, useful in illustrating the 
drawing model used within palette 
objects. To paint each cell, we will draw 
a filled polyline in its particular color 
using the GpiBeginPath, GpiHove, GpiPoly- 
line, GpiEndPath, GpiSetColor and GpiFill- 
Path APIs. The shape of the polyline fig¬ 
ure to be drawn will be defined by a 
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new method for our object class, which 
we'll call QuerySampieShape. 

When the user double clicks the 
mouse pointer on the square of color or 
clicks the mouse pointer on the Edit 
push button, the override wpEditCeU 
method created earlier is called. 
Through this method, we communicate 


allows—after the information has been 
saved within a private dialogue struc¬ 
ture—for user selection of the color 
wheel to be sent back to the color 
palette once the notification message 
has been received from the color wheel 
within the dialogue. 



(continued from page 52j 

will cause SOM to make each method in your class a non-static function, starting with 
the prefix you specify. This saves a lot of pain because SOM creates default static func¬ 
tions for each method, leaving you without symbolic information for your methods, 

• If you can't stomach the thought of working in assembler all the time without the benefit of 
your source code, you can use the IBM PM Debugger (IPMDL To use the IPMD source level 
debugger, you will need to run it as your Workplace Shell process. This is easily achieved 
by changing the RUNWQRKPLACE environment variable in your CONFIG.SYS file: 

RUNWORKPLACE=IPMD _ EXE 


• When you reboot your machine, the debugger will now come up in place of the Workplace 
Shell. You can now start, stop, and restart the Workplace Shell process at will. The pro¬ 
gram to run is PMSHELL.EXE in the 0S2 directory 


Setting breakpoints in your object class code can appear near-impossible at first glance. 
However you will find that setting a load breakpoint on the DLL that contains your object 
class—when PMSHELLEXE has been loaded, but before you run it—works nicely. When 
you hit the load breakpoint for your DLL, go ahead and stick breakpoints in your code on the 
stuff you're trying to debug. Remember that when you are tracing through code that makes 
method calls, it does not call you method directly. This can make source level debugging 
quite painful because you don't have source for SOM itself, the code that figures out what 
method to call, This trick is to not trace into a method call, but rather to stick a breakpoint 
on the method override that you've added. Alternately, through IPMD, you can step debug 
into the method. The button on the tools bar is: 


• Debugging an object-oriented program is very much like debugging a PM application. That 
is, your method overrides and new methods can be invoked at any time by the system or 
from your own code If you really want to know what is going on, try sticking a breakpoint 
on each and every method and override in your class to see when and how it is used. 

• Finally, if you at first you don't succeed, reboot your machine and try again. It has been 
know to fix many a problem or two or three or... 


with the ColorPickingDialog using a pri¬ 
vate message HSGJDITCELL* 

This message is given the current 
cell color and cell information, which 
allows it to set the cross hairs of the 
color wheel to the current color within 
the color palette swatch. It also 


STARCOLORPALETTE 
SAMPLE OBJECT CLASS 

To get back to a point made earlier, it is 
possible for an object class to inherit the 
behavior of every method defined by 
its parent class and write a very small 
amount of code to implement the new 


function you wish to add. As an exam¬ 
ple, consider the code in Figure 8 for an 
object class derived from the Color- 
Palette object class. All this derived 
class does is override the QuerySample- 
Shape method so the palette cell entries 
are drawn as star shapes instead of rec¬ 
tangles of color. Using the provided 
source code, try creating other simple 
subclasses of the Color Palette object 
class. This will allow you to get familiar 
with the tools and processes needed to 
create Workplace Shell object classes. 

REXX INSTALLATION PROGRAM 

Once our object classes are written, the 
final step is to install them into the 
Workplace Shell and create some 
instances of those classes. This can be 
done through the WP Class List object 
shipped with the OS/2 toolkit, found in 
the PM Development Tools folder con¬ 
tained in the Toolkit 2*1 or Toolkit 2.0 
folders. It is, however, worth illustrating 
how easy it is to register and create 
object classes using a simple REXX com¬ 
mand file, as shown in Figure 9. 

Notice that the REXX procedure is 
able to specify various parameters to 
the palette objects using the setup 
string parameter* This technique is very 
similar to passing control data to a PM 
control window as it is created; howev¬ 
er, instead of a complex structure, the 
object setup string is just a series of 
key=value pairs separated by semicolons. 
All classes of Workplace Shell object 
support at least a few setup string key¬ 
words. For more examples, study the 
file INI.RC (installed on any OS/2 2.x 
machine in the \0S2 directory on the 
boot drive). This script file is used to 
create all standard objects that can be 
seen after OS/2 installation. 

COLOR SAMPLE CONTROL 
WINDOW CLASS 

Now that we've created a color palette 
object class that exists within the con¬ 
fines of the Workplace Shell application 
process, we will create a simple win¬ 
dow control that allows that palette 
functionality to be accessed from any 
application program in the system. 

The average OS/2 user is already 
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familiar with the concept of picking a 
color, font, or scheme from a palette of 
predefined values. So why not make 
that function available globally? 

When the user pushes the Edit 
Color... push button (like that in Figure 
10) displayed on the color sample con¬ 
trol, that control communicates with 
our Workplace Shell palette object class 


SOH.Scope BOOL 50MLINK clrsj}uery$anple$hape( 
ColorPalette *som$elf> 

PPOINTL pPoints, 

PULGNG pcPoints) 

♦define STAR.CPOIHTS 11 

static PGINTL 

ptlStar[STAR_tPOINTS] = { { 20, 0 } t 

{ 30, 40 }, 

{ 0, 60 >, 

{ 30, 60 >, 

{ 50, 100 >, 

{ 70, 60 >, 

{ 100, 60 >, 

{ 70, 40 >, 

{ 80, 0>, 

{ 50, 30 }, 

{ 20 , 0 > >; 

if ( pPoints ) 

memcpy(pPoints, ptlStar, 

STHtCPflUTS * s±zeof (POINTL)); 
if { pcPoints ) 

♦pcPoints - STAR^CPOXNTS; 
return TRUfc; 



Figure 8. C source code for StarColorPalette class 


so a view of the standard color palette 
appears. Having this functionality in 
several applications would allow the 
user to create a set of favorite colors, 
each stored within a single color 
palette—and then have easy access to 
them from any application. If a user is 
not satisfied with the colors that exist 
in the palette, he or she can always 
bring up the color picking dialogue 
and revise the color choices. 

CONTROL SAMPLE CODE 

The sample control will communicate 
with the Workplace Shell object, using 
the WinSetObjectOata API call to pass a 
setup string parameter from the appli¬ 


cation process where the control lives 
to the actual palette object (which Lives 
under the Workplace Shell process}. 
The method of creating the setup string 
parameter well use to get our palette 
to display itself is shown in Figure 11. 

It causes the shell to open the palette 
object in palette view or to resurface an 
existing open view of the palette. When 


decides that the palette doesn't contain 
a suitable color, he or she just brings 
the color picking dialogue up to select 
another color into the palette. Neat, eh? 

COMING UP 

Beginning in our next article, we will 
implement a replacement to the list box 
control. Not only will the list box cir- 


SysRegisterObjectCLass("ColorPalette', 'CLRPALET'); 
SysCreateObject('WPFolder', 'Palette Folder",, 

'<WP_DESKT0P>',, 

'OPEN-ICON;QBJECTXD=<PALETFLDR>', 'update"); 
SysCreateObject('ColorPalette', 'Color Palette',, 
"<PALETFLDR>\, 

"OPEN-DEFAULT;QBJEQTD=<CLRPALET>", "update'); 
Figure 9. REXX installation code 



Figure 10. Color sample control 


the user picks a color, the palette then 
sends a notification back to the window 
handle to inform it of the new color 
choice. 

This allows users to pick colors from 
different applications using a single 
palette of colors. If at any time the user 


cumvent the 64K limitation, it will be 
enhanced to allow for direct manipula¬ 
tion of text, columns, and other good¬ 
ies. So stay tuned over the next few 
issues while we develop the control 
into something you can use every day 
in your own programs. 
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CHUR szSetup[100]; 

HOBJECT hObject; 

/* Print our window handle into the setup string so that the 

* palette can communicate back to us 
*/ 

sprintf (szSetup, "OPEN=DEFAULT;CTRLHDL=Ux\ (ULQNG)hwnd); 

/* Send the setup string through to our installed instance of 

* ColorPalette object class 

*/ 

if ( (hObject = WinQueryObJ ect ("<CLRPALET> 11 )) != 

(HOBJECT)NULL ) 

WinSetObjectData(hObject, szSetup); 

Figure 11. Object data setting code 


REFERENCES 

OS/2 2.0 Programming Guide Volume 11 (IBM Doc. SIOG-6494) 

OS/2 2.0 Presentation Manager Programming Reference Volume II (IBM Doc. 
S10G-6265) 

The source code can be downloaded from several electronic sources: 

• In the U.S., call the IBM PCC BBS at (404) 835-6600. The source code for this 

article is in File Area 11 under the name WPOBJ.EXE. 

• In Europe, you can find the source code on the International OS/2 Users 
Group BBS at +44 (0)454 633197 or +44 (0)454 633420. 

• On CompuServe, the source code is in LIB13 of the OS2DF2 forum, 

• If you have a VM account on an IBM node, you can receive the source 
code with the command REQUEST WPOBJ.EXE FROM BANZAI AT 
CARVM3. 
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This article describes how to write Workplace Shell-compliant applications in C language, exploiting the API 
prototyped in PMWP.H. by stefano maruzzi 


Writing WPS-Compliant 
Applications 


here are now two kinds of OS/2 applica¬ 
tions: basic porting from the 16-bit world 
and the newer 32-bit SOM-integrated 
development. While the latter Is the best way to 
write reusable code, it requires a deep redesign of 
applications to fully exploit object-oriented tech¬ 
nology, The guidelines offered in this article are 
an extract from OS/2 2.1 Workplace Shell Program¬ 
ming by Stefano Maruzzi. 

One of the distinctive features of OS/2 2,1 Is 
the adoption of an object-oriented interface called 
the Workplace Shell (WPS), a complex multi¬ 
threaded OS/2 application automatically execut¬ 
ed as the system boots. WPS exploits the standard 
Presentation Manager (PM) API to create a com¬ 
plete window, window context menus, and other 
structural components. In addition, objects pro¬ 
vided by the System Object Model (SOM) of OS/2 
enrich the WPS interface. SOM is a tool to develop, 
package, and distribute objects among applica¬ 
tions. Every object class defined by WPS derives 
on a class, SQMCLass, the ancestor of all objects in the 
system. WPS objects are placed in separate DLLs 
and developed according to the standard mecha¬ 
nism adopted for either EXE or DLL modules in 
the traditional PM programming scheme. 

Once a DLL is created, it is necessary to register 
it in WPS. The API function yinRegisterObjectdassO 
takes care of this operation, instructing WPS to 
load that specific DLL at every following boot. 
Similarly, WinDeregisterObjectQassO removes an 
object class from the WPS internal list. Almost 
everything found in the OS/2 System folder is an 
object (more specifically, an instantiation of an 


object). The Color Palette, the Font Palette, and the 
Templates folder are objects based on WPS classes. 

Once opened, objects take the form of windows 
on the screen. From a user's perspective, there is 
no way to distinguish between a WPS object and 
an application window. The title bar contains the 
window title, while the resizing icons to the right 
of the title bar let the user either hide or maximize 
the window. This is the result of mixing SOM 
objects and PM window classes. 

WHAT WPS IS 

Upon careful examination, WPS is basically a sub¬ 
classed window of class ^CONTAINER. The parent 
window, a traditional frame without any frame 
control, is always hidden behind it. The frame's 
parent is the desktop, as shown in Figure 1. 

As stated earlier, one of the most publicized 
feature of OS/2 2.1 is its object-oriented interface 
(as compared to the application-oriented interface 
of MS Windows and OS/21.x). In Windows, drag- 
and-drop operations always start from File Man¬ 
ager where this undocumented logic is Imple¬ 
mented. In WPS, in contrast, every object present 
in the shell is a valid source and target of a drag 
operation, with no preliminary discrimination. 
You can drag a document to either the printer or 
the shredder. The shredder itself can be dragged to 
a second level folder (a folder inside the desktop 
folder), and so on. 

From these direct manipulations, one can get 
the impression that drag-and-drop operations are 
system-wide. Although if you analyze WPS behav¬ 
ior from a user perspective this judgment is eor- 
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DESKTOP WINDOW 


HWNDJJESKTOP 


WPS FRAME WINDOW 


WCCONTAINER 


Figure t Relationship between the desktop and WPS 


hwndFrame = WinCreateStdWindow( HVND.DESKTQP, 

OL, 

^flFrameFlags, 

VC.CONTAINER, 
szWindowTitle, 

ccsjuTorasmoN | ccs.extenosei, 

NULLHANDLE, 

OL, 

fthyndOient) ; 

// set the frame window as the owner 
Win$etOwner( hundCLient, hwndFrame) ; 


Figure 2 , A client that is a window of one of the fifteen predefined window classes 


reet, from a PM developer's point of view, the 
focus is quite different. WPS, despite its role in an 
OS/2 system, is basically a traditional PM applica¬ 
tion with a frame window of class VC. FRA ME and a 
client class, HC.CONTAINER. Everybody can achieve 
this goal by simply using VC.CONTAXNER as the class 


name in yinCreateStdVindowO. In Figure 2, the identi¬ 
fier hwndQient refers to the container window. 

The net result is the absence of a window pro¬ 
cedure under developer control. The whole flow of 
messages generated by the user interactions direct¬ 
ly reaches the VC.CONTAINER window procedure; this 
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Notification 

Code 

Value Description 

CN.DRAGIFTER 

101 

Sent to the owner after the receipt of a DM_DRAGQVER in the container with 

CURDEREDTARGETEWPHA5IS or C A _ MIX EOT A RGETEMPH ASK, and with a display mode 
of Name, Text or Detail. 

OLDRUGLEHE 

02 

Sent to the owner after the receipt of a DH_DRAGLE*VE. 

CNJRAGOYER 

103 

Sent to the owner after the receipt of a DHJRAGOVER and when the container does not 
have the attribute CA_ORDEREDTARGETEMPHASIS and is in the display mode Tree or Icon, 

CN.DROP 

104 

Sent to the owner after the receipt of a DM„DR0P. 

CNJROPHELP 

105 

Sent to the owner after the receipt of a DM_DROPHELP. 

OLENTER 

106 

Sent to the owner after the pressing of the Enter key, or after a double¬ 
click with the selection button. 

cnjnxtdrag 

107 

Sent to the owner when a dragging operation is initiated. 

CN.EHPfMSIS 

108 

Sent to the owner when a record attribute changes in the container. 

CN.KILLFOCUS 

109 

Sent to the owner when the container loses focus. 

CN.SCROLL 

110 

Sent w'hen scrolling takes place. 

OLQUERYDELTA 

111 

Sent to get additional information when a scrolling is being executed. 

CN_SETFOCUS 

112 

Sent to the owner when the container acquires focus. 

CH _REALLOCPSZ 

113 

Sent to the owner before the editing phase of one of the container's items 
terminates (CIILENDEDIT). 

CN_BEGINEDIT 

114 

Sent when a text string is being changed in the container. 

CHjran 

115 

Sent to the owner when the editing phase of one of the container's items 
terminates. 

CN _C0L L A PS EIRE E 

116 

Sent after a tree structure is collapsed in the tree view display mode. 

Cli.EKPANDTREE 

117 

Sent after a tree structure is expanded in the tree view' display mode. 

CN.HELP 

118 

Sent to the owner after the receipt of a HR JELP. 

CN_CONTEKTMENU 

119 

Sent to the owner when the container receives the message U M_C0NTEXTM EMU. 


Table 1 . List of alt notification codes for the WLCONTJHB class 


is why the WPS client is subclassed. 
The detour in the flow of messages 
reaches first a window procedure 
inside the application and then the 
class window procedure where the 


container logic resides. 

If you consider WPS basically a 
WC.CONTAINER window, the judgment 
about the object-oriented interface 
changes drastically. All supposedly 


system-wide operations instead take 
place inside the same container win¬ 
dow or in a parent-child relationship. 
According to the VC_CQNTAINER naming 
convention, an object is a record (that 
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is, a block of memory privately han¬ 
dled by the class), This chunk of memo¬ 
ry is composed of standard informa¬ 
tion, integrated by additional data spe¬ 
cific for that object. 

The classic distinctions in four object 
categories (folders, applications, data 
files, and devices) is, therefore, inap¬ 
propriate from a development point of 
view. They all are icons (records) inside 
one container, and the difference 
between the objects depends on the 
kind of data hooked to each one (object 
specific information). Every record in a 
container has some standard data (a 
RECORDCORE structure) containing basic 
information such as the image dis¬ 
played on the screen and its text. The 
developer adds to this data new infor¬ 
mation to better qualify a record. This 
is exactly what has been done in the 
development of WPS. 

Usually the object-specific data 
amount to a greater quantity than the 
size of a standard RECORDCORE structure. 
All this information is undocumented. 


DRAG-AND-DROP OPERATIONS 
IN A CONTAINER 

In every OS/2 demo, you have been 
shown how easy it is to drag a docu¬ 
ment on the printer or to destroy it by 
dropping if on the shredder. All these 
operations occur inside the same con¬ 
tainer window and are managed 
through DfL messages and CN_ notifica¬ 
tion codes. OS/2 2.1 offers a set of sev¬ 
enteen messages specifically designed 
to describe every event related to drag- 
and-drop. These messages are always 
sent {they bypass the application mes¬ 
sage queue, reaching the destination 
window procedure directly) to the win¬ 
dow underneath the cursor hot-spot, 
and eventually to the target window. 
The WC^CONTAINER class, like any other 
predefined window class, has its own 
set of messages (CMJ, window styles 
(CCS_), and notification codes (CN_). 
When an event occurs in a container 
window, the owner is notified via a 
WM_C0NTR0L message with the notification 
code packed in the second short in mpl. 
Some of the nineteen CN. notification 
codes (the set is listed in Table 1) relate 



Figure 3. Flow of messages for the WPS application 


POINTER RETURNED - 
BY CM_ALL0CRECORD 

POINTER TO THE 
NEXT RECORDCORE 
DATA STRUCTURE 


POINTER TO THE 
NEXT RECORDCORE 
DATA STRUCTURE 



RECORCORE DATA STRUCTURE 

OBJECT-SPECIFIC DATA 

RECORCORE DATA STRUCTURE 

OBJECT-SPECIFIC DATA 

RECORCORE DATA STRUCTURE 

] 

OBJECT-SPECIFIC DATA 


Figure 4. Data associated with each record object in a container window 
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specifically to drag-and-drop on a con¬ 
tainer window* 

To implement drag-and-drop in a 
container, it is sufficient to intercept the 
DM_ messages received in the target win¬ 
dow as a consequence of the call of 
DrgDragO in the source application or to 
trap notification codes in the contain¬ 
er's owner window procedure. Despite 
the complexity and the quantity of data 
involved, in many circumstances drag- 
and-drop refers to the same container 
window or strictly related window 
(another folder with a parent relation¬ 
ship to the WPS client window). Data 
comes from and reaches the same kind 
of object (i.e. y a container). 

Subclassing a ^CONTAINER window 
offers the opportunity to intercept all 
DH. messages generated during a drag- 
and-drop manipulation. For WPS, all 
the CN_ notification codes reach the 
frame window procedure. To achieve 
this goal, you need only remember a 
simple though intriguing detail By 
default, all the frame controls in a stan¬ 
dard window refer to the frame win¬ 
dow as their owner. This rule, howev¬ 
er, doesn't apply to the client window, 
which has no owner, fn WPS, the 
client's owner is explicitly set to the 
hidden frame window to intercept all 
notification codes. This is a wise thing 
to do when the client is a window of 
one of the fifteen predefined window 
classes, as shown in the last portion of 
Figure 2. 

Based on this assumption, let's 
examine the information that reaches 
the frame window. Notification codes 
such as CNJRAGINIT, CNJRAGQVER, and 
CNJJRQP contain in mp2 a pointer to some 
class-specific data structures like CNR- 
DR1GHCU (Figure 5) and CNRDRAGINFO, These 
structures are very simple and have 
few members. 

When the user starts dragging an 
object inside a container, its owner 
receives a CN_INTTDRAG notification code, 
which collects valuable information in 
CNRDRAGINU The second member in CNR- 
DRAGBJU is a pointer to a RECORDCORE struc¬ 
ture (Figure 6), the data type where all 
record information is stored. 

Among the RECORDCORE members there 


typedef struct _CNRDRAGINIT 
{ // cdrginit 

HWND hwndCnr ; 

PRECORDCORE pRecord ; 

LONG x ; 

LONG y ; 

LONG ex ; 

LONG ey ; 

} CNRORAGDIIT ; 

typedef CNRDRAGINIT +PCNRDRAGINIT ; 

Figure 5* The CtiRORhGIRIT data structure 


typedef struct ^RECORDCORE 
{ // reec 

ULDNG cb ; 

OLONG flRecordAttr ; 

POINTL ptllcon ; 

struct ^RECORDCORE tpreccNextRecord 
PSZ pszlcon ; 

HPOINTER hptrlcon ; 

HPOINTER hptrMxnileon ; 

RBXTMAP hbmBitmap ; 

HBITMAP hbmMiniBitmap ; 
PTREEITEMDESC pTreeltemDesc ; 

PSZ pszText ; 

PSZ pszName ; 

PSZ pszTree ; 

> RECORDCORE ; 

typedef RECORDCORE *PRECQRDCORE ; 
Figure £ The RECORDCORE data structure 


typedef struct _CNRDRAGINFD 
{ // edrginfo 

PDRAGINFO pDraglnfo ; 

PRECORDCORE pRecord ; 

} CNRDRAGINFQ ; 

typedef CNRDRAGINFD +PCNRDRAGINFQ ; 

Figure Z The CNRDRtGIUlFO data structure 

are handles to icons and bitmaps to 
represent a record (object) on the screen 
in different views—icon, tree, and 
detail. This means that an application 
always knows the object aspect when 
dragging starts. Furthermore, the 
developer sets the object-related text 


typedef struct _DRAGINF0 
// dxnfo 
{ 

ULONG cbDraginfo ; 

IISHORT ebDragitem ; 

USHQRT usOperation ; 

HWND hvndSource ; 

SHORT xDrop ; SHORT yDrop ; 
USHORT editem ; 

USHDRT usReserved ; 

> 

DRAGINFO ; 

typedef DRAGINFO *PDRAGINFQ ; 

Figure £ The DR A GINFQ data structure 
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typedef struct DRAGITEM 

{ 

// ditem 
HWNO hwndltem ; 

ULONG uIItemID ; 

HSTR hstrType ; 

HSTR hstrRMF ; 

HSTR hstrContainerName ; 
HSTR hstrSourceName ; 
HSTR hstrTargetName ; 
SHORT cxOffset ; 

SHORT cyOffset ; 

USHORT fsControl ; 

USHORT fsSupportedOps ; 

} 

DRAGITEM ; 


typedef DRAGITEM *PDRAGITEM ; 

Figure 9 The DRUGITEM data structure 





DRAGINFO 

20 bytes 


DRAGITEM 

36 bytes 


DRAGITEM 

36 bytes 


DRAGITEM 

36 bytes 







Figure 10. Memory block allocated by an 
application system before executing a drag 


(i.e. the writing underneath the icon on 
the desktop) in the last three members. 

In Figure 7, we examine CNRDRAGINFO 
to understand how this information is 
passed to the target container (maybe 
the WPS window itself or an inner fold¬ 
er) after the user releases the right 
mouse button. 

This structure has a member of type 
PDRAGINFO, a pointer to a DRAGINFO struc¬ 


ture, and a pointer to a RECORDCORE struc¬ 
ture. The access to a DRAGINFO data struc¬ 
ture provides all information related to 
a drag-and-drop operation in WPS, as 
shown in Figure 8. 

All data associated with the mouse 
during the dragging of one or more 
objects is packed in a memory block of 
variable size. At the beginning is a DRAG¬ 
INFO structure, followed by as many 
DRAGITEM structures as instructed by the 
cbDragltem member (Figure 9). Figure 10 
illustrates how information is stored by 
the source application before starting a 
drag process. 

Once again, even in the case of a drop 
onto a container window, WC.CONTAINER 
information and direct manipulation 
data are strongly related. The last three 
HSTR members contain useful informa¬ 
tion for the target window. The handle 
to the string in hstrContainerName refers to 
the source container. Considering that in 
OS/2 2.1 a folder is the equivalent of a 
directory in the file system, this means 
that the physical origin in the file system 
is always known by the target. 

The opposite is never true; right 
now there is no way for the source win¬ 
dow to find out where an object is 
placed. I'm referring specifically to 
when an object is either moved or 
copied between two WPS folders. The 
feedback provided by WPS is limited 
to a series of DH.DRAGOVERNOTIFY messages, 
with mpl pointing to a DRAGINFO structure 
slightly modified according to the 
return value of the DM.DRAGOVER message. 
The source window of the direct 
manipulation gets the target window 
handle as the return value of DrgOragO. 
From this point on, 1 have defined an 
empirical way to obtain the full path¬ 
name of the target destination of a pre¬ 
vious drag-and-drop. Once you have a 
handle, it is easy to query the window 
title. The first portion of it is the direc¬ 
tory name, from which you can jump 
back to the complete pathname. 

To summarize, in the case of a con¬ 
tainer window (despite the fact that the 
source and the target containers are 
either the same or different windows), 
the information provided through the 
notification codes (CN_) and direct 


manipulation messages (DM.) offer a 
detailed view of what is happening in 
the system. 

DRAG-AND-DROP OPERATIONS 
WITH DIFFERENT WINDOWS 

Problems arise when you try to 
exchange information via drag-and- 
drop with another running application 
such as an editor. The worst situation is 
when the flow of information is from a 
WPS object to an application. In this 
case, a good portion of the information 
usually provided through a RECORDCORE 
data structure is no longer available 

Even in the case of a 
drop onto a container 
window, VC.CQNTMNER 
information and direct 
manipulation data are 
strongly related. 



because the target application is not a 
window of class WC.CONTAINER and the 
two processes don't share the same 
address space. 

On the other hand, when the source 
of information is an application and the 
target is WPS, you need only prepare 
the DRAGINFO and DRAGITEM structures 
according to what WPS expects (revert¬ 
ing to DrgDragFilesO, as in the copy of 
multiple files, doesn't require filling in 
any DRAGxxx data structure). The internal 
support to drag-and-drop is limited to 
container windows, a big disadvantage 
because one objective is to write WPS- 
compliant applications that are well 
integrated in the system shell. The solu¬ 
tion to this problem lies in writing spe¬ 
cific code inside each application that 
makes it drag-and-drop aware. 

Despite this lack of truly system-wide 
object management tools, a smart devel¬ 
oper can bypass this limitation with a 
hint of imagination and some experi- 
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ence. This result can be achieved by writ¬ 
ing plain C code and interacting with 
WPS objects as if they were windows. I 
always spend a lot of time trying to 
design an intuitive user interface to my 
applications; in one case, 1 designed a 
kind of panel window that was original¬ 
ly empty. Its surface is divided in two 
columns and six rows (both dimensions 
are variable). Each cell of the panel can 
accept an object represented as an icon. 
The user selects one object from the 
desktop and drops it in on empty cell 
The result is shown in Figure 11. 

The PANEL application is basically a 
valueset window, one of the five new 
predefined window classes added with 
the introduction of OS/2 2.x. Like the 
VC.CONTAINER class, WC^VJlLUESET has some 
specific notification codes related to 
direct manipulation. While it is easy to 
understand that a drag is occurring (a 
valueset receives the standard DH_ mes¬ 
sages), when the user releases the right 
mouse button there is no RECORDCORE data 
structure to supply all that valuable 
information. To obtain the object icon 
in that case, I refer to yinLoadFi!eIcon(), a 
new API prototyped in PMWP.H. This 
function loads an application icon from 
different sources {but doesn't always 
work properly). This is exactly what 
WPS does in the General page in Note¬ 
book Settings when changing the object 
icon via drag-and-drop. 

The code quality of applications 
such as PANEL would greatly benefit 
from better-documented WPS behav¬ 
ior. Considering that every program 
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Figure It Panel window in which each cell of the panel can accept an object represent¬ 
ed as an icon 


has to interact with WPS, knowing how 
the system shell responds to every 
event is a primary need. 

Conclusion 

OS/2 2.1 offer a broad range of tools to 
develop easy-to-use applications. The 
key components are drag-and-drop 
support and an extensive use of WPS 
objects (with the addition of new class¬ 
es), If developers follow this approach 
to the use of WPS objects, a set of new 
and exciting applications will fully 
exploit the power of OS/2 2.1 in the 
near future. 
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This article describes IBM's microkernel technology, examining its architecture and associated programming 
abstractions. It also describes how the microkernel can be used as the foundation for a highly modular, portable, 
and secure operating system that can support multiprocessor and multiple operating system personalities. 

BYPYLEELENNIL 


The IBM Microkernel 
Technology 


r he IBM microkernel technology is based on a 
Mach microkernel originally developed by 
Carnegie Mellon University. It also contains 
selected technologies developed by the Open Soft¬ 
ware Foundation Research Institute, as well as func¬ 
tionalities implemented by IBM. The major features 
of the microkernel can be summarized as follows: 

■ Simplified architecture 
• Expandability 
• Portability 
* Multiprocessor support 
* System security. 

The microkernel provides a simple, highly modular 
and extensible architecture compared to a tradition¬ 
al operating system kernel. Extensibility allows 
many traditionally kernel-based operating services 
to reside outside the kernel at the user process level. 
In the traditional operating system, services such as 
process management, virtual memory manage¬ 
ment, network management, file system services, 
and device management are all built into the kernel 
This results in a cumbersome and inflexible kernel 
that is difficult to enhance or port to different hard¬ 
ware platforms. These system kernels also normally 
support uniprocessor and are inherently less secure. 
The microkernel, on the other hand, is highly 
secure. It provides only basic system services such 
as task and thread management, interprocess com¬ 
munication, virtual memory services, I/O, and 
interrupt services. These sendees are made avail¬ 
able to user-level tasks through a set of microkernel 
interface functions. The small kernel also facilitates 
real-time support, as only a minimum of kernel 
code must be executed. 

Unlike in a traditional operating system, sendees 


such as file system, network sendees, and device 
drivers operate outside the microkernel as user- 
level servers, as shown In Figure 1. The clean sepa¬ 
ration of kernel senders reduces complexity, increas¬ 
es portability and requires fewer entries into the 
kernel level to perform operating system functions. 
In addition, the servers allow the creation of a high¬ 
ly modular operating system that can support mul¬ 
tiple system personalities and sendees by configur¬ 
ing them as user-level servers. 

The microkernel is easily portable to different 
computer platforms due to the clean separation of 
machine-dependent and machine-independent 
code. Machine-dependent and device-dependent 
code is located in the microkernel; porting to a new 
hardware platform mainly involves rewriting the 
machine dependent code. 

The traditional operating system kernel is not 
very secure, with security features built outside the 
kernel. The microkernel, on the other hand, is 
designed weith security as an integral feature of the 
system. The microkernel operates on system 
resource objects such as virtual memory space, files, 
and processors. User-level tasks access these objects 
by sending messages through highly secure com¬ 
munication channels called ports. 

In a traditional operating system, device dri¬ 
vers operate at the privileged level. Under the 
microkernel, however, they operate at the user- 
process level, above the kernel. This means that 
device drivers can be developed and debugged 
just like user programs; this also increases porta¬ 
bility info other hardware platforms. Since the 
device drivers are privledged microkernel tasks, 
they get access to I/O resources such as I/O ports. 
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memory-mapped devices, and direct memory 
access (DMA) through the microkernel services. 
Interrupts are normally intercepted by the micro¬ 
kernel, which decides whether to handle the inter¬ 
rupt or send it to the user-process level device dri¬ 
vers. These drivers must be registered with the 
microkernel and must maintain interrupt handlers 
waiting to service the interrupts. 

MICROKERNEL ARCHITECTURE 

The microkernel provides the following program¬ 
ming abstractions, from which other operating sys¬ 
tem functionalities can be derived: 

Task. A program running under the microkernel is a 
task. Each task owns a collection of resources such as 
virtual address space, threads, and ports. The micro¬ 
kernel provides each task with protected access to 
system resources through ports, communication 
channels maintained by the microkernel. A task can 
communicate with other tasks through ports. In a 
client /server environment, a client task can request 
services from a server task using interprocess com¬ 
munication. Tasks may be created, terminated, sus¬ 
pended, or resumed by other tasks. When a new task 
is created, it can inherit virtual address space and 
port capabilities from its parent task. 

Threadl A thread is the smallest independent unit 
of execution (instruction stream) running within 
a task. Each task requires at least one—possibly 
more—concurrently executing threads to perform 
a computation. Threads share the task address 
space and all other task resources such as virtual 
memory, file descriptors, and ports. Threads are 
scheduled to a processor by the microkernel, 
which allows multiple threads to run concurrent¬ 
ly within a single task's memory space. For exam¬ 
ple, a multithreaded program may use one thread 
to compute a mathematical formula while anoth¬ 
er is used to receive user input. Multithreaded 
tasks provide programs with greater performance 
and modularity. In uniprocessor environments 
the use of threads increases the performance of 
the task by overlapping the execution of the com¬ 
putation and I/O threads. In a symmetric multi¬ 
processing environment {one in which processors 
share the same physical memory), the microker¬ 
nel allows threads in a multithreaded program to 
execute in parallel on different processors. This 


results in substantial improvement in the task's 
performance. 

Objects. The microkernel is object-oriented in 
nature. All microkernel services and resources such 
as tasks, threads, virtual memory regions, files and 
processors are represented as objects. Each object 
provides a set of operations that can be invoked by 
sending messages to that object, which in turn 
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Figure 1 . IBM's microkernel-based operating system structure I reprinted from IBM Micro¬ 
kernel Technology, IBM Corp. f June 1993) 


invokes the functions that correspond to each oper¬ 
ation. For instance, data can be read from a memo¬ 
ry object by sending a message to that object. When 
a task creates an object, it receives a port name, 
which represents the object, and port rights, which 
give the task restricted access rights to the object. 
The object concept can also be extended into a net¬ 
work environment, where objects can exist on any 
system in the network, A task can transparently 
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invoke these remote objects using inter¬ 
process communication. 

Ports. Ports are communication channels 
used to send and receive messages 
between two tasks. The port is the basic 
object reference mechanism; it can be 
used to invoke operations on objects 
such as virtual memory regions, files, 
processors, tasks, and threads. A port is 
a queue managed by the microkernel, to 
which messages from a sender task are 
appended by a Send operation. The mes¬ 
sages are then taken out by a recipient 
task through a Receive operation. Ports 
are protected by a capability mechanism 
so that tasks with appropriate send and 
receive capabilities can access them. This 
means that only a task with receive 
rights can obtain messages sent to a port 
and only tasks with send rights can send 
to it. Tasks can create ports for their own 


case of blocking communication, the 
message is transferred directly to the 
receiving task when it invokes the 
Receive operation. For nonblocking com¬ 
munication, the message is passed in 
two stages, first from the sender to the 
kernel and then from the kernel to the 
recipient. IPC also supports the 
client/server computing environment 
by allowing communication between 
tasks running on different networks 
through message servers. 

Virtual Memory. Microkernel virtual 
memory support provides large paged 
address spaces to the tasks. The micro¬ 
kernel supports the concept of memory 
objects when using the virtual address 
space. It manages the physical memory 
as a collection of memory objects, which 
can be mapped into a task's virtual 
address space. A memory object can be 


The IBM microkernel technology is based on a 
Mach microkernel originally developed by 
Carnegie Mellon University. 


use; to establish communication with 
other tasks, they may also send port 
capabilities to other tasks with mes¬ 
sages. Furthermore, using network 
servers, port capabilities can be extend¬ 
ed transparently over a network to 
invoke objects residing on different sys¬ 
tems. Port capabilities are highly secure 
because they are hard to forge or create 
fraudulently. 

Interprocess Communication. Interprocess 
communication (IPC) is a mechanism 
that allows communication between 
two tasks. IPC uses messages to pass 
information between tasks; a task sends 
a message to a port and another task 
receives it from the port. A message con¬ 
sists of a fixed length header followed 
by a collection of data including port 
capabilities and references. Messages 
can be exchanged using blocking or 
non-blocking communication. In the 


a virtual memory page, a set of pages, or 
a secondary storage object such as a file. 
A file object mapped into the address 
space can be read or written like a nor¬ 
mal memory object. When a process ter¬ 
minates, its mapped file objects are 
automatically stored back into the file 
system with all changes. You can associ¬ 
ate a port with each memory object. 
Ports can be used to send messages to 
the memory object in order to request or 
transmit memory object data. 

The microkernel allows a server task 
outside the kernel to manage virtual 
memory. This task, known as an exter¬ 
nal pager, has access to memory objects 
stored on a disk. When virtual memory 
is allocated, an external pager may be 
specified to handle paging requests. If 
no external page is specified, a default 
pager is used. 

The microkernel also allows tasks to 
share memory objects as well as transfer 


large amounts of data between tasks. It 
uses a technique called copy-on-write 
(lazy evaluation) that allows tasks to 
share memory objects without copying 
the pages associated with those objects. 
Initially, the pages to be shared are 
marked as read only. As long as the 
tasks make only read reference to these 
pages nothing is changed. A write to any 
of the pages generates a page fault; the 
microkernel creates new copies of those 
pages. The microkernel also provides a 
mechanism to efficiently transfer large 
amounts of data between two tasks. The 
sender task sends a pointer to the data 
area, called "out-of-line data," to the 
receiving task. When the recipient 
receives the message, the microkernel 
simply maps the pages to the destination 
task's address space, thus avoiding the 
physical transfer of data between tasks. 

Host and Processor Set. The host and 
processor set are functions used by 
applications that utilize advanced oper¬ 
ating system features. The host feature 
gives information about the processor 
complex running the system, as well as 
functions such as date, time, and sys¬ 
tem stop and restart. The processor set 
features are used in multiprocessor 
machines to group processors into 
classes. These classes allow a parallel 
application to execute multiple threads 
simultaneously on different processors 
in the machine to achieve true parallel 
execution. 

Server Tasks. The microkernel supports 
special application-level tasks called 
personality and personality-neutral 
servers that provide operating system 
personalities and services. There are 
two types of servers. Personality 
servers are used to create operating 
systems such as DOS, OS/2, and AIX, 
allowing multiple operating system 
personalities to coexist on a single 
machine. In contrast, traditional oper¬ 
ating system services such as file sys¬ 
tem, device, and network services are 
built into personality-neutral servers. 
For instance, the master server may 
load other personality servers and they 
all can share a common file system 
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server, device drivers, and default 
pager, as illustrated in Figure L The 
servers communicate with each other 
through ports via interprocess commu¬ 
nication. 


MICROKERNEL 
HIGH-LEVEL INTERFACES 

The microkernel provides two high- 
level program interfaces that help pro¬ 
grammers develop multi-threaded and 
client/server applications. 


Microkernel interlace Generator (MIG). 

Programs using microkernel inter¬ 
process communication often follow the 
client/server programming paradigm in 
which clients send a message to request 
services from a server and receive data 
via another message. To relieve the pro¬ 
grammer of the tedious task of setting 
up and sending messages, the microker¬ 
nel provides an IPC interface generator 
called MIG. MIG is a compiler that takes 
a specification of a message-passing 


I The IBM microkernel provides the core 
technology for a next-generation operating 
system. 


CONCLUSION 

The IBM microkernel provides the core 
technology needed for the development 
of a next-generation operating system. 
Its multiple operating system personali¬ 
ty support allows applications written 
for different operating systems to be run 
concurrently on the same machine. The 
multiprocessor support allows applica¬ 
tions to achieve maximum performance 
from multiprocessor hardware. The rel¬ 
atively small kernel supports real-time 
applications. The ability to maintain and 
access objects over a network allows dis¬ 
tributed computing. Finally, the inher¬ 
ently secure and easily portable micro¬ 
kernel allows the creation of secure 
operating systems on a variety of hard¬ 
ware platforms. 


C Threads . The IBM microkernel pro¬ 
vides a set of low-level functions to cre¬ 
ate and manage multithreaded pro¬ 
grams. Using these low-level APIs gives 
complete control of a thread, but it also 
requires handling machine dependen¬ 
cies, requiring programmers, for exam¬ 
ple, to set up the state of a thread. The 
microkernel also provides a set of high- 
level C language interface functions 
called C threads that help users create 
multithreaded programs rather than 
using low-level thread functions. (These 
routines are contained in the C threads 
library.) A major benefit of the C thread 
functions is code portability; the library 
provides machine-independent func¬ 
tions to create and control threads. The 
C thread library also contains functions 
to coordinate multiple threads, shared 
variables, and mutual exclusion for crit¬ 
ical sections. This frees the programmer 
from developing complex thread syn¬ 
chronization mechanisms. 


interface and a procedure call interface 
and generates appropriate C language 
code for both client and server pro¬ 
grams. This eliminates the need for the 
programmer to implement the packing, 
sending, receiving, and unpacking of 
IPC messages. An additional benefit is 
that generating IPC code through MIG 
eliminates the chance for programming 
errors caused when code is written 
manually. 


Pylee Lennil, IBM Corp,. WOO N W 5tst 
St, Boca Raton Fla , 33429, (407) 443-3855 . 
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programmer in the IBM entry systems tech¬ 
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While much has been written in the trade press about the Personal Computer Memory Card International Asso¬ 
ciation (PCMCIA), most articles tend to focus on PCMCIA's current capabilities. This article explores the cards' 
potential, using on IBM PCMCIA Data/Fax Modem as an example, by dana beatty 

Programming PCMCIA: 

It's All in the Cards 


he PCMCIA standard has come a long way 
since the concept was first formulated in 
1989. Initially designed only for memory 
card devices, it has since grown to encompass I/O 
implementations such as modems, 3270, Token- 
Ring, and Ethernet cards. Originally supported by 
few manufacturers, PCMCIA has matured to the 
point where the IBM PS/2E desktop system is 
dependent on PCMCIA 
architecture. IBM hopes 
that PCMCIA software 
will make the same pro¬ 
gression. While other 
system manufacturers 
use PCMCIA heavily in 
notebook and laptop 
computers, IBM also 
uses the cards in its 
desktop systems. 

PCMCIA cards are 
distinct from standard 
PC adapter cards in 
several ways: 

* PCMCIA is its own 
bus; the cards are 
neither ISA bus nor 
Micro Channel. 

* PCMCIA is nonproprietary; it is the same 
across IBM and non-IBM systems. 

* Memory and I/O registers for the card can be 
mapped into any available space on the host 
system; users needn't deal with dip switches or 
system reconfiguration utilities. 

* The cards can be inserted or ejected while the 


system is running. 

* They are lightweight and easy to use. 

* Cards are completely encased; there is no need 
to worry about their ruggedness. 

UNTAPPED SOFTWARE POWER 

Because the proficiency of most PCMCIA manu¬ 
facturers is limited to the actual card hardware, 
most of the burden for 
Interoperability and 
usability of the devices 
has fallen on PCMCIA 
system and operating 
system providers. In the 
last year, IBM began 
shipping the key PCM¬ 
CIA software elements 
(socket services, card ser¬ 
vices, and client drivers) 
with its PCMCIA sys¬ 
tems, operating systems, 
and PCMCIA cards. 
Each of these software 
elements has a logical 
home. Figure 1 illustrates 
the PCMCIA software 
architecture. 

PCMCIA Software Architecture. Socket services, the 
lowest software layer, interacts directly with the 
system hardware chip that controls the PCMCIA 
socket. Socket services is concerned with tasks such 
as fielding interrupts generated when a card is 
inserted or ejected from a system. Because the chip 




PCMCIA card 
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Figure 1 . PCMCIA software architecture 


that supports the socket varies from system to sys¬ 
tem, socket services could reside in system BIOS; 
today, however, it ships with the system as a 
device driver or similar configuration. 

Card services communicate with socket ser¬ 
vices to provide a more generalized set of func¬ 
tions for managing PCMCIA cards. Card services' 
main function is to manage and coordinate the use 
of system resources, such as IRQs and memory 
space, among all PCMCIA devices in the system. It 
provides a set of functions accessed by client dri¬ 
vers through its API. Because its implementation is 
operating system-specific, card services would 
most logically be shipped with the operating sys¬ 
tem, as IBM does with DOS 6,1 and OS/2 2*1, Cur¬ 
rently, to facilitate an interface with card services, 
OS/2 client drivers must be written as device dri¬ 
vers. 

Client drivers communicate with card services 
to manage specific types of PCMCIA cards (such 


as flash cards) or even a specific implementation of 
a PCMCIA card (such as the IBM PCMCIA 
Data/Fax Modem). As the name implies, pro¬ 
grams register as clients of card services. During 
registration, a client indicates a set of events, such 
as card insertion and ejection, it is interested in 
monitoring. When an event occurs, card services 
notifies all clients registered for that event via the 
client's callback handle. For example, inserting a 
card into the system generates an interrupt. Socket 
services fields the interrupt and informs card ser¬ 
vices of the activity. In turn, card services notifies 
each client registered for the card insertion event. 
The client callback routine determines that a card 
has been inserted into the system. From there, the 
client driver interrogates the card information 
structure (CIS), the content and organization of 
which is defined by the PCMCIA standard, to 
determine if it is the card or type of card the client 
driver is managing. 
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Card Information Structure. The CIS is a 

linked list of data structures called 
tuples. The information contained in a 
tuple is used not only to initialize the 
card but also to automate the opera¬ 
tions and configuration of associated 
applications. Figure 2 shows an 
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figure Z PCMCIA card information structure 


Hex 

Value 

Tuple 

Function 

Description 

17 

CISTPl.FUNCE 

Function Extension 

Tuple 

04 

TPl.UIIK 

Link to next tuple; 

4 bytes follow 

00 

TPLFE.TYPE 

Serial description 

02 

TPIFE.IM 

16550 UART 

OC 

TPIFE.UC 

UART capability, 
even, odd parity 

7F 

TPIFEJJC 

UART capability, 

1 stop, 5-7 char 


Figure 3, IBM High-Speed Data/Fax Modem serial port 
identification function extension tuple. The value 17x is 
assigned by PCMCIA for the function extension tuple 
(nSWL_FUHCE). 


overview of the CIS organization. 

A tuple cannot exceed 128 bytes in 
length; the first byte denotes its func¬ 
tion. The PCMCIA specification defines 


a set of tuple functions such as 
CISTPL_FUNCE, which details functional 
information about the card. The second 
byte, known as the tuple link (TPL_LINK), 
contains the number of bytes until the 
start of the next tuple in the CIS chain, 
thus linking one tuple to the next. 

For example, the IBM High-Speed 
Data/Fax Modem contains several 
CKTPLfUNCE tuples. Figure 3 shows the 
serial port identification function exten¬ 
sion tuple, while Figure 4 shows the fax 
Class 2 function extension tuple. 
Although both of these tuples are CIST* 
PL.FUNCE types, Figure 3 details the 
UART capabilities while Figure 4 
details the fax Class 2 capabilities of the 
modem. Also note that the TPLJJNK field 
value varies between the two tuples. 
Figure 3 contains only four bytes of 
information after its TPLJJNK field, while 
the tuple in Figure 4 has seven bytes. 
Yet both are CISTPL.FUNCE tuple exam¬ 
ples. Together, these examples show 
the types of capabilities described in 
the CIS tuples, 

TYING IT ALL TOGETHER 

While the power of CIS information 
may not be readily obvious, consider 
how data or fax applications are 
installed, configured, and operated in 
today's environment. 

Ideally, a PCMCIA data/fax appli¬ 
cation could perform several functions. 
It could be a card services client driver, 
functioning as both an application and 
a data/fax client driver. When the 
application is invoked, it would regis¬ 
ter with card services as a client inter¬ 
ested in the card insertion and ejection 
events. The application would, in this 
way, gain control and interrogate the 
card to find out whether it is a modem 
card and determine its capabilities. 

Instead of asking for information 
regarding COM port assignment, speed, 
and even fax capabilities during installa¬ 
tion, none of this information would be 
required to support a PCMCIA data/fax 
modem, because that information 
resides on the modem's CIS, The 
data /fax application could interrogate 
the CIS to make these determinations. 

To do this, the client driver would 


issue the card services GetConfigura- 
tionlnfoO function to receive basic 
information {such as manufacturer 
identification) on the card. With this 
information, the client could determine 
if a modem were inserted. 

If a modem were indeed present, the 
first order of business would be to allo¬ 
cate unclaimed resources, such as a 
base address and an IRQ level, to it. 
Because data/fax applications general¬ 
ly expect a modem to be mapped to 
architected COM port resources such as 
COM2 (or a base address of 02F8x and 
IRQ level 3), current modem client dri¬ 
vers resort to these same values to 
insure compatibility with these existing 
applications. This setup stifles the 
inherent power of PCMCIA. 

But if a data/fax application were 
to drive the PCMCIA modem as a 
client driver, card services could be 
allowed to assign any free address 
space and IRQ, rather than a specific 
one, because the application program 
could adjust to accommodate the new 
base address and IRQ values returned 
by card services. 

Additionally, by combining PCM¬ 
CIA client driver support into the 
data/fax application, there is no longer 
a need to query end users for informa¬ 
tion such as COM port assignments 
during the installation process. In other 
words, because the application is the 
client driver managing the PCMCIA 
modem, it will request the COM port 
assignment dynamically when the card 
is inserted into the system. 

WHATSIT ALL MEAN? 

With today's modems, COM port 
resources are statically reserved for a 
device regardless of whether the device 
is used during that session. With PCM¬ 
CIA and client drivers, resources can be 
acquired only when the associated 
device is present and any resources 
available when the card is inserted can 
be utilized. This is accomplished via 
the RequestlRQQ and RequestlOO func¬ 
tions. For example, a PCMCIA modem 
client driver could loop through the 
various IRQ levels until it successfully 
obtains one. 


78 


OS/2 DEVELOPER 
























Once the data/fax application client 
driver acquired the necessary IRQ and 
I/O address space, it would then inter¬ 
rogate the card's CIS further. To tra¬ 
verse the CIS/ a client can use the Get- 
FirstTupleQ and GetNextTupleO functions. 
These functions return the tuple func¬ 
tion (OSTPLJUNCE) and link (TPL.LHK) 
fields, as shown in Figure 3, Alternate¬ 
ly/ a client may advance directly to a 
particular tuple of interest. In the case 
of the PCMCIA High-Speed Data/Fax 
Modem, a client driver may wish to 
skip directly to the first CISTPL_FUNCE 
tuple to access the modem capabilities. 
To do so, a client would enter the CIST- 
PL_FUNCE value into the "DesiredTuple" 
field within the GetNextTupleO function. 
Once card sendees locates the tuple, the 
client driver would then issue the Get- 
TupleDataO function to retrieve the infor¬ 
mation contained within that tuple. 

In the case of the PCMCIA data/fax 
modem, while processing these tuples 
the client driver would learn the speeds 
supported by the card (14.4 kbps for 
both data and fax) as well as its fax 
capabilities (Class 1 and Class 2), 
Because it could interrogate the card, 
an application would not need to poll 
the user during installation. Addition¬ 
ally, should the user choose to insert a 
different PCMCIA data/fax modem in 
the future, the application would not 
need to be reconfigured because it 
would dynamically adjust itself based 
on the capabilities of the modem as 
defined on the card's CIS. 

Another feature that could be incor¬ 
porated into a data/fax client driver is 
a prompt that would alert users to 
insert a card in the event that they 
attempt to transmit a fax or data while 
the card is absent from the system. 

Finally, when the user removes the 
modem from the system, socket ser¬ 
vices would field the interrupt and 
notify card services of the event. Card 
services would then notify each client 
driver that registered itself for the 
CARD_REHGYAL event. After determining it 
was the PCMCIA modem card that 
was ejected from the system, the 
modem client driver would then free 
the I/O address space and IRQ 


resources it had allocated to that card 
with the ReleaselOO and ReleaseIRQO 
functions. 

In the case of a PCMCIA modem, an 
existing data or fax application could 
be modified to incorporate the client 
driver functions. 


THE FUTURE OF PCMCIA 

The industry as a whole agrees that the 
future of PCMCIA is bright. The soft¬ 
ware building blocks are there, and 
PCMCIA seems poised for even greater 
success if only a "killer" application 
were there to exploit it. 
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Hex Value 

Tuple 

Function Description 

REFERENCES 

17 

dSTPL.FUNCE 

Function Extension Tuple 

PCMCIA Standards (including the 

07 

TPLJUBC 

Link to next tuple; here 7 bytes follow 

Card Services API) is available from 

23 

TPLFEJTPE 

Fax description 

PCMCIA, 1Q30G East Duane Ave*, 

03 

00 

OF 

TPLFEJF 

data rate 

Sunnyvale, Calif*, (408) 7200107. 

TPLFEJH 

modulation: V21, V27, V29 

For a detailed description of the 

00 

TPLFEJY 

data encryption 

IBM PCMCIA Data/Fax Modem 

22 

TPLFE.FS 

fax feature, polling T.4 

CIS, refer to the IBM PCMCIA and 

00 

TPLFE.CF 

country code not supported 

Internal Data/Fax Modems Technical 
Reference (IBM doc* S42G-2181). 

Figure 4. IBM High-Speed Data/Fax Modem Fax class 2 function extension tuple 
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The Advanced Novice 

In this issue we introduce a new section, "The Advanced Novice," for programmers just beginning to explore the 


world of OS/2. This article deals with a concept basic to object oriented programming—reusable code and 
reuse techniques, by Joseph H. mcintyre 


Reuse: Recognizing 
The Opportunities 


f or many years, the job definition of a sys¬ 
tems analyst was identified with the term 
"efficiency expert" and the elimination of 
redundant manual processes. The work involved 
determining current processes, their products, 
and the factors surrounding and affecting, or 
being affected by, each process. With the collec¬ 
tive knowledge about the processes, an analyst 
could create alternative methods, either by apply¬ 
ing new models or replacing the current model 
with a known better model. The selected alterna- 

■ Knowledge is fundamentally 

reusable; collecting and distributing 
that knowledge is the challenge. 


tive model could then be monitored and evaluat¬ 
ed; if successful, it could be applied elsewhere. 
The efficiencies from each successful model built 
on previous models and became foundations for 
the next. 

REUSE IS NOT NEW 

Reuse is a cornerstone of the analyst's task* 
Improving processes through the elimination of 
redundancies can be the easiest route to identify¬ 
ing, assessing, quantifying cost savings, and 
implementing new systems. Application of suc¬ 


cessful models to new processes reduces time to 
enact and lessens the chance of repeating short¬ 
falls of previous implementations* The concept of 
reuse, of course, may also be applied to the work 
of the analyst. 

SOME EXAMPLES 

In software development today, many people con¬ 
sider reuse to encompass only code libraries and 
object-oriented programming technologies. This is, 
however, a narrow and restrictive view. 

Knowledge is fundamentally reusable; collect¬ 
ing and distributing that knowledge is the chal¬ 
lenge, Tips and Techniques documents can be col¬ 
lected from many users' experiences. The result¬ 
ing information may be combined and released as 
a book or on-line reference, or placed in a reposi¬ 
tory. Users can use it to record or build detailed 
information suitable for their environments. 

Operating system API calls are designed to he 
applicable to many applications, making it prefer¬ 
able to utilize the API instead of writing new sub¬ 
systems specific to an application. For instance, in 
OS/2 the window management APIs are used by 
graphical programs. While these APIs may be 
extended by an individual application where 
desired, they would never he entirely replaced. 
Because PM's extensible architecture offers stan¬ 
dard methods for implementing extensions (for 
example, subclassing and DLLs), working with 
extensions is relatively straightforward. 

Test cases for an application may be run on 
multiple workstations with differing configura- 
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tions by including setup variables or environment 
settings for variables such as hardware installed, 
network names, and connections. This allows test 
plans and test cases to be moved to a different 
environment used in subsequent releases, or used 
to test companion products. 

REUSE THROUGHOUT THE 
DEVELOPMENT CYCLE 

If reuse—and the processes for developing 
reusable deliverables—is applied to all phases of 
the software development process, there are many 
opportunities for improvements. Each phase holds 
different opportunities, but deliverable candidates 
for reuse are best identified and prepared before 
they are produced. This leads to design with mini¬ 
mal restrictions on reuse. 

In the analysis phase, reuse can eliminate repet¬ 
itive work. Searches for past models, data dictio¬ 
naries, new business models, and concurrent pro¬ 
jects may yield knowledge applicable to a current 
project. Other projects can be enhanced by saving 
even the information not directly used on a project 
(it is also wise to retain information in case the 
analysis is later reviewed). 

Applying reuse to architecture-level designs 
can yield design documents that can be applied 
across platforms or projects much more readily 
than code derived from them. It is also easier to 
expand or limit concepts at the design stage. The 
important distinction between design and code is 
that code is a single implementation of a design. In 
many cases, design documentation is much more 
useful to a subsequent user than is the source code 
itself. (At a minimum, the code can be used as a 
reference.) An excellent example of this is the con¬ 
trast between the API reference and Programming 
Guides from the OS/2 toolkit. It would be very 
difficult to program for Presentation Manager 
using only the API reference without the concepts 
presented in the Guide, 

In the coding phase, suitability for reuse is 
determined by a number of factors including the 
tools used, the physical state of the code (how 
modular, whether there are global variables, nam¬ 
ing conventions, and so on), and the quality of the 
code (in the context of both the original application 
and other possible applications}. The following 
sections give some guidelines. 


Compiler Languages. It is best to consider your reuse 
goals before determining the language you will 
use to pursue them. There are several pitfalls to 
watch for. 

If you work in a mixed-language environment 
(this includes a single language used on multiple 
platforms), it is important to anticipate translation 
and connection hurdles. Assembler is not easy to 
read or understand; libraries may be limited to a 
specific platform or compiler and some languages 
cannot call subroutines written in other languages. 
An emerging technology is the language-indepen¬ 
dent System Object Model (SOM), which allows 
the creation of bindings that let applications and 
objects written in different languages communi¬ 
cate transparently. 


In many cases, design 
documentation is much more 
useful to a subsequent user than 
is the source code itself. 


Modularity is very important. It is desirable to 
have the smallest meaningful component that can 
be utilized with minimal effort. This may refer to 
anything from a single function to a complete sub¬ 
system. For example, CenterWindow is a single 
function reusable component that positions a win¬ 
dow in the center of another window. At the other 
extreme, Lotus 123 for OS/2 and Freelance Graph¬ 
ics for OS/2 share the same graph engine. In both 
of these examples, the reusable component pro¬ 
vides a well defined, concise function to the appli¬ 
cation it serves. 

If a product will be extensible by a customer, 
consideration of the customer is important. In 
some cases, source code is required, which may 
not be acceptable for the vendor. 

Source code (not just comments) must be read¬ 
able and logically organized. Well-structured code 
has meaningful variable names, related functions 
grouped logically, and well-organized modules if 
a task involves code in more than one source file. 


NOVEMBER/DECEMBER 19 9 3 



Your Own Repository 

This is an easy but effective way to introduce reuse concepts unobtrusively. The users leam to think about presenting 
materials in forms suitable for peers to make use of and see the usefulness of having a common knowledge source that 
is always available. {You may even want to use this concept on a standalone machine for your own work. Et can be a 
good personal organizer, especially if you frequently 'change hats/) 

Creating the repository 

1. Create a directory on a network server, 

2. Set up client workstations to see this directory with read, write, update, and create directory rights. Delete 
may be restricted. 

3. Distribute simple instructions for users of the repository {this may include environment-specific infor¬ 
mation). 

Using the repository 

To add a new subject, create a subdirectory. Topics within a subject may be added by creating a subdirectory within a 
subject subdirectory. 

Create a new entry, or update an existing one, with an editor/word processor. Make sure the format is compatible 
with other users (this should be addressed in the instructions from step 3 above). 

Suggestions 

Use HPFS to allow long file names to be used. Eight-letter names are not very practical or usable. 

Use a navigation tool {the Drives object is an example) to move around the repository. This will save typing and file 
name quoting issues with tong names. Double clicking on the file icon will bring up the file in the editor. 


Table l A simple knowledge repository 


Concept level from a repository object description 

A phone number consists of 10 digits in the format (123) 456-7890, where (123) is an area code representing a region and 
the remaining seven digits represent a unique number within the region. The second digit of the area code is always 0 or 
1, No area code starts with 0 or 1 and no customer number begins with 0 or 1. 

Design level from a repository dictionary 

Data Type: numeric, 10 digits, no decimal positions. 

Validation; all digits required, if not null. First number in range 2-9 inclusive, second number in range 04 inclusive, 
fourth number in range 2-9 inclusive. Format; (123) 456-7890 

Table 2. Reusable components for a phone number 


Coding conventions such as module 
file names, file header comments, and 
code formats make navigation and 
reading easier. 

Testing, In the testing phase, reuse may 
include maintaining test cases across 


product releases, sharing test cases 
between products (for example, using 
the same services of the operating sys¬ 
tem) and bringing unit-test cases for¬ 
ward from programmers to testers. In 
both automated and manual environ¬ 
ments, a well designed test case suite 


can provide a good reuse foundation 
with little additional effort. 

Many test cases are exactly the same 
except for one or two steps; the first 
reuse candidate is therefore the test 
cases themselves. Creating a test case 
should start with foundation cases and 
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be filled out with specific cases that 
address differences. A foundation test 
case may not be a full case; instead it 
may provide environment information 
and application setup on which other 
cases will build. Future test cases may 
be built by extending this foundation 
case, rather than using a more compli¬ 
cated existing case and removing 
unnecessary steps. 

Most test cases would run identical¬ 
ly on all machines—except for a few 
machine-specific variables like the net¬ 
work name for the workstation or a 
server name* Test cases should not 
include hard-coded names; instead, 
they should use aliases, variables (in 
the case of automated tools), or general 
names (for manual cases). These allow 
names to he configured for individual 
workstations. 

Often, while a test case is running, 
a new error is found for which a test 
case does not exist, A new case, based 
on the current one, should be created 
to ensure that the condition will be 
tested. If a framework exists, genera¬ 
tion of the new case is easy; the foun¬ 
dation case for the current test case 
can be extended to test the new condi¬ 
tion. 

installation and Maintenance. The deliv¬ 
ery and maintenance phases have a dis¬ 
tinctive reuse opportunity, namely the 
installation and service programs. 
Install programs all do the same thing, 
more or less—copy files, set up the user 
environment for the application, possi¬ 
bly do initial program setup to cus¬ 
tomize applications for the user. Ser¬ 
vice programs check service levels and 
replace files; they may provide other 
services like rollback of changes. 

There are many installation pro¬ 
grams, ranging from simple batch pro¬ 
grams to full graphical interface appli¬ 
cations. Applications that come with¬ 
out an install program are natural 
candidates for reuse. 

If you don't have a solid install 
base on which to build, products that 
provide this foundation can be a good 
starting point for creating custom 


install and service programs. These 
include the Stirling Group's Install 
Shield and IBM's Software Installer 
for OS/2. 


THE FOUNDATION FOR REUSE 

The foundation for effective reuse is 
documentation. Specifically, the entire 
software cycle for a component must be 
available in complete, accurate, and 
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Concept level from a repository object description 

A phone number consists of 10 digits in the format {123} 456-7390, where (123) is an area code representing a region and 
the remaining seven digits represent a unique number within the region. No area code starts with 0 or 1 and no customer 
number begins with 0 or 1. For numbers assigned before 1994, the second digit of the area code is a 0 or 1. Starting in 
1994, the second digit is not restricted. 


Design level from a repository dictionary 

Data Type: numeric, 10 digits, no decimal positions. 

Validation: all digits required if not null First number in range 2-9 Inclusive; second number in range 0-1 inclusive, ser¬ 
vice year < 1994; second number not restricted, service year 1994; fourth number in range 2-9 inclusive. 

Format: (123) 456-7890 

Table 3. Changes to reflect a possible area code change scenario 



sufficient documents. This allows you 
to determine the applicability of a com¬ 
ponent to another project with no prior 
knowledge of that component. Ideally 
(and to be effective in large systems), 


grams or forms. Even paper in a cen¬ 
tral filing cabinet is a start. The impor¬ 
tant point is that there is a common 
repository (or repositories) that people 
know how to access. A simple reposito- 


The foundation for effective reuse is documen¬ 
tation. Specifically, the entire software cycle 
for a component must be available in complete, 
accurate, and sufficient documents. 


these documents should be in a form 
suitable for retrieval in an interactive 
browsing environment. 

Absent of an electronic environment 
providing advanced search capabilities 
within the context of components, there 
are many other effective storage and 
retrieval techniques. The most basic is a 
collection of facts in a knowledge base, 
which can range in scope from a primer 
on a business process to an encyclope¬ 
dia in a CASE tool. From this set of 
facts, viewers can retrieve information 
from the data. For a text file, many 
tools can provide search and hyperlink 
capabilities; the data in a CASE tool 
encyclopedia can be displayed as dia¬ 


ry is described in Table 1. 

A component always contains a con¬ 
cept; it may also contain any number of 
stages through one or more implemen¬ 
tations. Following are some examples 
of different components. 

Phone number 

* Concept—an explanation of the 
valid phone number sequences for 
all numbers around the world, 
include information such as the for¬ 
mat expected by each country. 

• Design—a logical data type descrip¬ 
tion to implement phone number 
data structures. Validation informa¬ 
tion such as country codes could 


also be documented. 

• Coding—Cobol copy book, C data 
structure, C++ class object model, 
and object class implementation. 

Using a Dynamic Data Exchange (DDE) 
server in an OS/2 program. 

• Concept—explanation of DDE ser¬ 
vices and where to use them; com¬ 
parison to other alternatives. 

• Design—implementation alterna¬ 
tives for creating DDE clients. 

• Samples—sample implementations, 
possibly in pseudo-code. 

• Coding—code fragments, working 
samples. 

In both these cases, the documents are 
easily extensible. In fact, the phone 
number could apply only to North 
American numbers, then be extended 
to included worldwide numbers. Note 
that in the phone number example 
actual code implementations were pro¬ 
vided, whereas in the DDE example 
samples were provided. With DDE, the 
subject is very dependent on its appli¬ 
cation; thus a generic solution is not 
likely to be useful. Templates are pro¬ 
vided, however, as a starting point. 

The important point is the availabil¬ 
ity of knowledge on a subject, not just 
the final implementation; not only the 
code can be reused; so can all the work 
that provided the knowledge on which 
the code was based. This has some 
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obvious advantages: 

• Collaborative work by experts. Each 
expert can provide specific knowl¬ 
edge, allowing those in other areas 
to expand the work. 

• Revisions can be documented 
throughout the entire component, 
applied at the level on which the 
change is most appropriate, and cas¬ 
caded through the other levels. 

• The structure for the documentation 
allows different people to work 
within a framework. 

• The structure helps people think in 
terms of components rather than 
whole solutions. 

This concept seems at first to introduce 
a lot of work. Much of this work, how¬ 
ever, is being done but is unrecorded. 
Top down, bottom up, and object-ori¬ 
ented design all break problems into 
smaller units. Reuse helps when units 
are discovered, during searches for an 
existing component that satisfies a 
need, or when creating a new reusable 
component. 

Tables 2 and 3 show the before and 
after images of two repository docu¬ 
ments for U.S. phone numbers. There 
is little work required to maintain the 
documents. 

Information on reuse can parallel 
that on object-oriented techniques. 
Reuse, however, extends beyond 
object-oriented work; the concepts 
apply to existing processes as well. 
Object-oriented environments do pro¬ 
vide additional facilities to implement 
reuse more effectively. 

A search for an existing component 
can be executed in one of several 
ways, depending on the component 
and the context of the need. For 
instance, the phone number search 
could consist of a search in a CASE 
tool repository and information from 
programmers or a long distance phone 
company. Searches vary depending on 
available information and additional 
requirements. 

Collected information should be 
stored in a repository (a CASE tool, a 
repository product, or even a text file 
in a known place) that makes the infor- 


File: USERPROF.IDL 

♦include <somobj.idl> 

interface UserProfile : SOMObject 

{ 

attribute string Name; 
attribute string NetworkName; 
attribute string WordProcessor; 
attribute string Spreadsheet; 

}; 

File: VUSERPRO.IDL 

♦include "userprof.idl" 

interface vUserProfile : UserProfile 

{ 

short UpdateProfile (in unsigned long hwndParent, 
in unsigned long hwndOwner); 

}; 

File: VUSERPRO.C 

♦define vUserProfile.CLass.Source 
♦include <vuserpro.ih> 

MRESULT EXPENTRY DialogProfileUpdate (HWND, unsigned, MPARAM, MPARAH); 

/* UpdateProfile displays a dialog with the current user profile 
object data and allows the user to change the values. The result 
returned will be DID.OK if the user saved changes. ♦/ 

SOM.Scope short SOMLINK UpdateProfile(vUserProfile somSelf, 

Environment *ev, unsigned long hwndParent, 
unsigned long hwndOwner) 

{ 

short sResult; 

/* Display dialog box */ 

sResult = (SHORT) WinDlgBox (hwndParent, hwndOwner, 

(PFNWP) DialogProfileUpdate, (HMODULE) 0, 
IDD.UPDATEUSERPROFILE, somSelf); 

return (sResult); 

} 


Figure 1 . Good reuse implementation (continued on page 90) 
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But our users are saying things 
that really make us proud. 
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T he prise: 1993 Discover Award 
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mation available for future use. This 
makes information more stable as 
knowledgeable people move and the 
knowledge they have acquired moves 
with them. 


AN EXAMPLE OF REUSABLE CODE 

Figure 1 shows a set of file fragments 
that demonstrate the separation of user 
interface code from application logic 
code in an object-oriented language. 
The example uses SOM, although the 
principles can be applied to other lan¬ 
guages that support inheritance. 

The application object is defined, 
followed by an object that inherits 
from it and adds the user interface 
functionality. The object user can 
decide whether to use the application 
object independently or with the user 
interface code. This setup also pro¬ 
vides multiple user interface imple¬ 
mentations for the single application 
object 

REUSE ISSUES 

This section is intended to provoke fur¬ 
ther thought on the applicability and 
benefits of reuse techniques. Try to 
envision these issues in the context of 
your environment. 

Reuse is the responsibility of the 
provider, not of the user. The provider 
contributes the knowledge and imple¬ 
mentations to the repository. The user, 
on the other hand, simply selects com¬ 
ponents from the repository for inte¬ 
gration into other products. If a com¬ 
ponent is not suitable, the user will not 
use it. It is therefore incumbent on the 
provider to provide components suit¬ 
able for use, given an arbitrary and 
demanding user. 

Components must be able to be 
pulled cleanly from their existing 
product and incorporated without 
disturbing the environment of the 
new product. Otherwise, the process 
becomes too difficult and leads to 
rework. An example of a good reuse 
component is an independent module 
that contains financial calculations for 
mortgages. 

If a component relies on one or 



Figure 1 . Good reuse implementation (continued from page 88) 


more other components, the interfaces 
should be clearly defined such that the 
dependencies can be replaced with 
functional equivalents. Dependencies 
should be documented so the depen¬ 
dent components' interactions with 
their dependencies need not be 
known. 

Documentation should be complete, 
accurate, and sufficient. The benefit of 


reuse is not realized if the user must do 
as much work using the component as 
writing a new one. All documentation 
should be maintained with the compo¬ 
nent; changes cannot be made at one 
level without updating the appropriate 
information in the other levels. The 
update in other levels may implement 
the changes or indicate the level to 
which the component complies if it 
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does not fully implement the changes. 
For instance, the design document for 
phone numbers could include country 
code, but the Cobol copybook may not 
implement international numbers. This 
would be stated in the Cobol copybook 
documentation. 

Reuse requires thought. It also 
requires vision to recognize some less 
obvious opportunities for reuse* Reuse 
can also inspire better solutions, 
adding a context in which picturing a 
component acts as a catalyst for new 
ideas* 

Applying reuse concepts does not 
require a new set of tools; these con¬ 
cepts can be applied to existing frame¬ 
works and extended to fit the require¬ 
ments of your environment. Practical¬ 
ly, enabling tools are necessary to 
facilitate searches through a large num¬ 
ber of components and provide reposi¬ 
tory services* But even if the concepts 
are applied only to individual work, 
they can provide insight into the func¬ 
tion and benefit of the techniques* 


REFERENCES 

Booch, Grady. Object-Oriented Design with Applications. Redwood City, Calif.: 
Benjamin /Cummings Publishing, 1991. (ISBN # 0-8053-0091-0) 

SOMobjccts Developers Toolkit (IBM Doc. 96F8647) 

Install Shield, The Stirling Group 

Software Installer for OS/2 (IBM Doc. 5621-434} 



CONCLUSION 

Reuse is often taken for granted. A goal 
of many development methodologies, 
it is being incorporated in a number of 
ways. Understanding the concepts and 
deliverables of a system in which reuse 
is utilized provides a dear vision of the 
environment and possible benefits. 
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IMer is not the pure and natural resource it once mas the effects of global manning, acid rain, 
and chemical technology have tampered with it. to protect our water from pollution, uie ash that you 
think about how you dispose of chemicals, garbage, and other contaminants. 


Here are same helpful hints. 

Adhering to these tips will 
benefit the water you drink, 
the water you swim and bathe 
in t and the food you eat 


1* Keep Your Trash Out of the Gutter: Sweep 
your driveways and sidewalks instead of hosing 
them with water. Put trash in the can instead 
of the gutter. 


3* Fix Your Car Leaks : Recycle your motor oil 
at your local mechanic or garage. Don't dump 
it into a storm drain. More oil enters beaches 
and lakes from urban runoff than from tanker 
spills, 


2* Get Rid of Garden Pests : Put ladybugs or 
praying mantis in your garden instead of using 
insecticides. Contact your local nurseiy for al¬ 
ternative ideas to herbicides and pesticides. 


4. 


Usemn-Toxks: Buy eartMrien (Byproducts 
now. Vinegar and baking soda are excellent 
cleaning agents. . 
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Thh article presents a programmer's view of LAN NetView and describes how to develop an application with 
the X/open XMP/XOM functions. In many cases, XOM functions are used to help build the objects and convert 
between private (used by the framework), and public (used by the developer) structures, by Jacob m. rzepka 
and CHUCK B. MCKELLEY 
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r his article introduces the concepts of XMP 
and XOM, which represent the primary 
programming interface for LAN NetView* 
It covers building and analyzing the data struc¬ 
tures associated with XMP/XOM and construct¬ 
ing simple management requests to agents devel¬ 
oped for LAN NetView. In an upcoming article, 
we will unite these programming concepts with 
the actual agent implementations and framework 
facilities provided by the LAN NetView Man¬ 
age/Enabler products. 

As described in the first article of this series 
("LAN NetView: A Programming Overview," 
OS/2 Developer, July/August 1993), LAN NetView 
is a platform or framework for the development 
and execution of applications used to manage net¬ 
work resources. It should not be confused with 
network managers, as it can manage a system 
rather than just a network. "System" here refers to 
applications and physical resources that can be 
addressed with Agents supplied or written by var¬ 
ious resource owners- Examples of resources 
include IBM's Database Manager, Communica¬ 
tions Manager/ 2, OS/2 2.0 and 2.1 products, 
router hubs, adapter cards, and so on. As an anal¬ 
ogy, LAN NetView can be considered an operat¬ 
ing system for management applications. It per¬ 
forms or provides many of the services common to 
all management applications, including memory 
management, transport services, request dispatch¬ 
ing, and information routing. 

There are currently three major protocols that 
define management interfaces. Simple Network 


Management Protocol (SNMP), Common Manage¬ 
ment Interface Protocol (CMIP), and SNMP 2. 
While the relative merits of each protocol are 
beyond the scope of this article; the subject has 
been covered extensively. At a high level, CMIP 
provides much more robust functionality than 
SNMP, but not without significant overhead in the 
implementing software and increased complexity 
in the specification of the operations to be per¬ 
formed, Today, although CMIP is gaining popu¬ 
larity, the vast majority of applications are written 
to the SNMP specification, and LAN NetView pro¬ 
vides support for both. Where not otherwise indi¬ 
cated, this article focuses on programming to the 
CMIP specifications. 

A final topic before getting into coding specifics 
is the transport of data between managing and 
managed nodes. By its very nature, SNMP uses 
TCP/IP to flow information between nodes. 
CMIP, unhampered by this restriction, has both 
CMOT (CMIP over TCP/IP) and CMOL (CMIP 
over Logical Link Control, or LLC). Within the 
LAN NetView framework, it is not vital that a 
developer understand the underlying transport to 
develop effective applications. All software writ¬ 
ten to function using the CMIP structures will 
operate transparently in both the CMOL and 
CMOT environments. LAN NetView's supporting 
APIs are not concerned primarily with the trans¬ 
port mechanism. APIs for SNMP and CMIP are 
similar and, as mentioned above, little or no dif¬ 
ference exists between CMOL and CMOT with 
respect to application development. 




PROGRAM DESIGN CHARACTERISTICS 

The LAN NetView products implement the 
X/Open Management Protocol (XMP) and 
X/Open Abstract Data Manipulation (XOM) API 
specifications and its implementation adheres 
closely to the X/Open specifications. Although 
there are a few minor differences, they typically 
have little or no impact on the developer, repre¬ 
senting a proper subset of the allowed function 
defined by the X/Open specifications. This feature 
is important since it assures some measure of 
portability with other platforms claiming support 
for XMP and XOM APIs. 

At a block diagram level, programs using the 
XMP/XOM API calls have a similar structure. The 
program is divided into four segments: object or 
data definition, initialization, operational, and ter¬ 
mination. 

Addressing application development, we begin 
with the initialization and operational stages of 
defining the application. These, in him, require the 
use of data structures that form the core of the 
application's definition segment. This article is 
intended as an introduction to building the 
required data structures, issuing management 
requests, and interpreting the results. The LAN 
NetView Developer's Reference Manual and LAN 
NetView Administrator's Guide provide more com¬ 
prehensive detail on the framework and program¬ 
ming structures. A set of samples are also provid¬ 
ed with the product. 

XMP 

The XMP/XOM API set is shown in Figure 1, 
which consists of collections of management verbs, 
administrative functions, and data manipulation 
functions. The protocol functions of XMP are bro¬ 
ken down to request functions and the corre¬ 
sponding response functions. The ability to man¬ 
date a confirmation or response is a configurable 
characteristic of the XMP API. These functions 
consist of the prefix mp_, the function name, and a 
suffix of either _req or .rsp. For example, the GET 
function is coded as mp_get_req{) and the response 
■P-get.rsp(). 

The administrative functions, which also have a 
mp_ prefix, are used to initialize or terminate an 
application within the NetView platform. All data 
constants and macros are written in capitals, while 


all functions are lowercase. In the following exam¬ 
ples, the macros and functions that contain the 
prefixes on_ or 0H_ are XOM functions macros and 
data constants used for the definition, manipula¬ 
tion, or deletion of data within defined data struc¬ 
tures. 

The general structure of a LAN NetView appli¬ 
cation (not including the data definition aspects) is 
shown in Figure 2. At a minimum, all LAN 
NetView programs must contain mp^initialize, 
inversion, and mp_bind function calls. These three 
functions establish a connection to the platform 
from within an application. The function mpj.ni- 
tialize is called first to define a workspace or data 
area, which holds the data structures that XMP 
and XOM require to operate properly. The second 
function, mp_version, defines characteristics of the 
interface and provides for loading of common rou¬ 
tines used to process data within the application. 

Finally, rnp.bind establishes the pathway to the 
framework that generates and returns responses 
to management requests. 

All LAN NetView programs must 
contain mp_initial ize, mp_ version, 
and np_bind function calls, which 
establish a connection to the 
platform from within an application. 


Since OS/2 is a multithreaded environment, it 
is possible to have multiple mp_bind functions for a 
single initialization request. This function is useful 
when management requests are responded to 
infrequently. For example, a request may report 
when a security or access violation occurs. Since 
these events are rare, a separate thread can be 
spawned for each resource for which security 
must be tracked, with each thread accomplishing 
totally different management functions and hav¬ 
ing its own mp.bind and specific management 
request. Although there is a limit of 30 mp_bind 
functions per mp.initialize, multiple workspaces 
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CMIS 

Service 

SNMP 

Service 

XMP Functions 

Descriptions (of request only) 

Action 

-- 

mp.action.reqO 

mp.action.rspO 

Requests that the responder perform one of 
the actions defined for an object 

Cancel Get 

" " 

!iip_caocel_get,req() 

mp_cancel_get_rsp() 

Requests that the responder terminate 
servicing an earlier asynchronous "get" 
request that has not yet completed 

Create 

-- 

mp_create_req() 

mp_create_rsp() 

Requests that the responder create an instance 
(object) of the specified object class 

Delete 

-- 

mp_delete_req() 

mpjelete_rsp() 

Requests that the responder destroy a 
particular instance (object) of an object class 

Get 

Get 

mp_get.req() 

rap^get.rspO 

Requests that the responder supply the 
value(s) of one or more object attributes 

Set 

Set 

mp_set_req{) 

mp_set_rsp{) 

Requests that the responder modify the 
value(s) of one or more object attributes 

Event 

Report 

Trap 

mp w event,report.req() 
mp.event,reportersp() 

Issues one of the notifications (events 
or traps) defined for an object 

-- 

Get 

Next 

rap.get.next.req() 

rap.get.next.rsp() 

Requests that the responder supply the type 
(name) of the next SNMP variable in the object 

XOM Functions 




Function Name 

Description 



oit_copy() 

Creates an independent duplicate of a private OM object 

om_copy_value() 

Copies a string from one private OM object to another 

om_create(} 

Creates a new private OM object of a particular class 

ott.decodeO 

Creates a private OM object that represents an encoded private OM object (see cwtencodeO below) 

om_delete(} 

Deletes a private or service-generated OM object 

om_encode() 

Creates a new private OM object that encodes an existing private OM object using the Basic 

Encoding rules for ASN1 

om_get{) 

Creates a public copy of all or part of a 

private OM object 

om_instance() 

Tests an OM object for membership in a particular OM class 

om_put() 

Puts attribute values of an OM object (public or private) into a private OM object 

om_read() 

Reads a segment of a string in a private OM object 

om_re<nove() 

Removes and discards an attribute value from a private OM object, or from the entire attribute 

om_vrite(} 

Writes a segment of a string into a private OM object 


Figure 1 . XMP functions to support CMIS and SNMP services 
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can be defined with multiple calls to 
the mp .initialize function. This applica¬ 
tion is diagrammed in Figure 3. 

The previous discussion centers on 
the fact that XMP/XOM uses synchro¬ 
nous calls as its default mode.With syn¬ 
chronous calls, a thread or process 
blocks or waits until the function exe¬ 
cution completes; whereas if an access 
violation never occurs, each thread 
waiting for an occurrence is blocked 
indefinitely. The platform also allows 
for asynchronous operation, in which 
control continues when a request is 
made. When the operation completes, 
the requesting application is signalled 
and the resulting data can be 
processed. In the previous example, a 
single thread or process using a single 
inp_bind could issue multiple requests 
asynchronously for access violation 
data, as shown in Figure 3. 

Once a bind is completed, it is possi¬ 
ble to issue a management request. For 
CMIP, possible requests include 
flip.get.req, np.set.req, mp.action.req, 
mp_create_ req, mp_event.report_req, 

mpjelete.req, or mp_cancel_get_req. Each 
function has a similar parameter set, 
hence the notion that these represent a 
single API of the form mp_m_req() or 
up_xxi_rsp() (see Figure 4). This article 
focuses on the mp.set.req function. 

For SNMP, only four functions are 
used: mp.get.req, mp_set_req, mp_get_next_req, 
and np.evefit.report.req. The mp_pt will be 
described in a later article; its relation¬ 
ship to the other functions can be 
inferred with little difficulty, 

PARAMETERS 

At this point we are ready to write our 
first application segment, shown in Fig¬ 
ure 5. Notice that the result of each API 
call is a status; this is important because 
only when the status indicates success 
is a valid result guaranteed. The result 
of each API call must be checked for a 
successful return before proceeding to 
the next function call. 

While it shows structure, Figure 5 
does not identify the parameters associ¬ 
ated with each call. The definition of 
the parameters leads to the data defini- 


workspace=fnp_initialize ( ); 
feature.Hst [0] ^ MP .CUB, PACK AGE; 
status-mp^version {workspace, feature list)}; 
if (status I = HP.STATUS) { 

printf {" inversion error’* \n); 

(void) om.delete (status); 
return (-1); 

> 

status^p.bindJHP.DEFAULT.SESSION, workspace, ftsession); 
if (status ! = HP.STATUS) { 

printf {" mp.bind error" \n); 

(void) 0 Jn_delete (status); 
return (-1); 

> 

status=mp_set_req) RPJEFMILT.SESSION, MPJEFAULT.CONTEXT, 

argument, ^result, iinvoke.id); 


mp_unbind (session) 
om_delete (session) 
mp.shutdown (workspace) 

Figure 2. Simplified structure of LAN NetVtew application 


We’d like to say a word about 
client/server development. 

TESTING. 

You've chosen the platform, architecture, 
development tools, and application. Now’s 
the time to decide how you're going to test 
your client/server applications. 

The Softbridge Automated Test Facility (ATF) 
lets you fully automate regression testing, 
letting you test "often and early" in the 
development cycle. And that means lower 
costs, decreased time to release, and higher 
quality results. 

If you're building client/server (or stand¬ 
alone) applications under OS/2, Windows, 
or NT, you should be using ATF to test them. 
To learn more about ATF, call 800-955-9190. 


ATF: The final 

word in testing. 


I ~T \ . Softbridge, Inc. 
617-576-2257 (Phone) 
617-864-7747 (FAX) 
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SYNCHRONOUS OPERATION 



PROCESS 


THREAD 1 

THREAD 2 

THREAD N 

MP_GET_REQ() 

MP_ACTION_REQ() 

MP SET_REQ() 

• 

• 

• 

• 

• 

• 

• 

• 

• 


ASYNCHRONOUS OPERATION 


PROCESS 

MP_GET_REQ() 

MP ACTION REQO 

MP_SET_REQ() 


Figure 3. Multiple workspaces defined with multiple calls to the mp_initialize function 


C-API Function (XMP API) 


MP.status 

ms_xxx.req( 



OM.private.ob ject 

session, 


OM.private.object 

context. 


OM.object 

argument, 


OM.private.object 

♦result.return 


OM.sint 

♦invoke.id.return); 

MP.status 

Success or an 

error object 

Session 

Management service characteristic 

Context 

Call specific characteristic 

Argument 

Function and View Specific Object 

Result 

Return-Function Dependent 

Invoke-Id-Return ID for Asynchronous Calls 


Figure 4. CM-API function (XMP API) 


tion aspects of programming to the 
framework and into the utilization of 
XOM functions (used in manipulation 
and creation of the complex data struc¬ 
tures used by the LAN NetView plat¬ 
form). As most developers discover, 
while the operational coding is very 
simple, the definition of parameters in 
the operational statements and the 
results of a management request tend 
to be rather complex. 

OBJECTS 

XMP and XOM rely on a definitional 
notation that specifically and unam¬ 
biguously defines a piece of informa¬ 
tion. Within the X/Open specifica¬ 
tions, these are referred to as objects. 
Objects are arrays of triplets called 
descriptors. The first descriptor in the 
array is a header and the last consists 
of nulls, as in Figure 6. The standard 
programatic representation is shown 
in Figure 7. 

Each descriptor consists of a type 
syntax and a value. The type field iden¬ 
tifies the descriptor, while syntax identi¬ 
fies the type of data represented by the 
descriptor and value contains either the 
data or a pointer to the data. For exam¬ 
ple, a descriptor may depict: 

memory.size,integer, 300 

Here the type is memory.size, its syn¬ 
tax is integer, and the value is 300. 
Descriptors can be more complex; the 
syntax field can describe a string or an 
object type (a pointer to an array of 
descriptors). For example, memory size 
can be represented in bytes, pages, or 
kilobytes. The descriptor definition 
might then have the structure shown in 
Figure 8. Structures can become very 
complex, with multiple levels of nest¬ 
ed object definitions. 

PACKAGES 

To begin coding, a developer must 
define the "packages" used by the 
application. Each package is a collec¬ 
tion of data structures defined for use 
with an associated agent or agents and 
represented by all or part of a DLL. 


Packages are identified in an object of 
type mp.feature, which is usually stati¬ 
cally defined. A sample feature list def¬ 
inition is given in Figure 9, section G. 
The feature list is used in the mp.version 
statement; the result of the mp.version 


function call can be used to check 
which DLLs are loaded. Unless space 
is at a premium, it is easiest to include 
all available packages in the feature list 
definition and reuse the code in each 
application. 
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ws=mp_intialize(); 

/* create a work area 

*/ 

s tatus=mp_ version (. *,); 

/* define the interface 

*/ 

status=mp_bind(,,.); 

/* Establish Connection to framework 

*/ 

$tatus=frip_set_req(...}; 

status^p.unbindQ; 

/* sever connection to framework 

*/ 

5tatus=mp_shutdoyn(); 

/* relinquish space 

*/ 


Figure 5 L Application segment structure 


PROGRAM INITIALIZATION 

The mp.initialize, mp_ version, and 
mp^bind functions are used to establish 
a connection to the framework. fnp_ini- 
tialize returns a handle to a data area 
used by successive functions, while 
inversion identifies the packages used 
by the application. The general form 
of the function call is 




static DH_descriptor name ={ 


onjid_dbc(om_cuss, CUSS JAME), 

/* Header Macro */ 

(type.syntax,value}, 


{type,syntax,value}. 


0 N U LL _0ESC RIPTO R }; 

/* macro representing nulls */ 


Figure 7: Standard programatic representation of array structure 



Figure ft Descriptor with syntax field describing memory size 


mp_v ersion(feature J_Lst, ms); 

As noted earlier, feature_list 
describes the packages to be loaded for 
application processing. Packages are 
collections of definitional structures 
that describe the data represented in 
the application* They are necessary to 
handle differences between platforms 
for representation of string and numer¬ 
ic information. For simplicity, use the 
feature list definition given in Figure 9, 
section G, The us parameter is returned 
from the rap.lnitializeO function* 

The final initialization function is 
mp_bind. Its syntax is 

mp Jjirad(session,us,ftbound_session); 
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The session parameter defines how 
a connection is made. A pointer to a 
data area for the session is returned for 
this function; a context must then be 
defined for execution of the operational 
mp.xxx.req functions. Fortunately, 
default contexts and default sessions 
exist. (For this article, explicit session 
and contexts will be defined.) The 
defaults assume confirmed synchro¬ 
nous calls, with a response required for 
each request. The session object pro¬ 
vides for caller identification, which is 
necessary for a response. 

To build the CONTEXT and SESSION 
objects, two XOM functions, om.create 
and om.put, must be introduced. (Note 
that all XOM functions have the prefix 
om_. XOM functions deal solely with the 
definition and modification of data 
structures, whereas XMP provides for 
the creation and reporting of data or 
operations, based on the contents of 
data structures.) The first step is to 
build a shell of the structure of interest 
using om.create, which allows the defin¬ 
ition of an object of the class specified 
as a parameter. To define an instance 
of the CONTEXT object, exercise the func¬ 
tion call: 

_create(MP_C_CONTEXT,OM.TRUE,ws ^con¬ 
text); 

This builds an empty context object 
pointed to by ^context. The second func¬ 
tion, om.put, allows us to complete the 
fields in the already-created context 
object. Its syntax is: 

oni_put(context,OM_REPUCE_ALL, con¬ 
text.opts, 0,0,0); 

om.put copies descriptors from the '"pub¬ 
lic" object context.opts into the "private" 
context object. These public-to-private 
conversions must be performed on 
many objects used in the framework. 

Public versions of the objects can be 
modified directly, which is why they 
are created; however, private versions 
of the objects are most efficiently used 
by the platform. The variable 
context.opts can be defined as an object 

Figure 9 Sample feature list definition (continued on page 99) 


static OM.descriptor context.opts ={ 

0N.0ID.DESC(0H_CLASS, HP.C.SESSION), 

{MP.MODE, OH.S.ENUMERATION,MP.T.CONFIRHED}, 

^ASYNCHRONOUS, 0M.S.B00LEAN, OH.FALSE} 

OM.NULL.DESCRIPTOR }; 

\ 

1 

1 

1 

1 

1 

static OM.descriptor req.title ={ 

0M.0ID.DESC(0M_CLASS, MP.C.ENTITY.NAME), 

{MP.ENTITY, OH.S.PRINTABLE.STRING,OM.STRING("TEST")}, 
OM.NULL.DESCRIPTOR }; 

1 

/* Section A*/ 

1 

1 

1 

1 

static OM.descriptor session.opts ={ 
OM_OID.DESC(OM_CLASS, HP.C.SESSION), 

{MP.REQUESTOR.TITLE, 0M.S.0BJECT,{0,req.title}}, 
OM.NULL.DESCRIPTOR }; 

1 

1 

1 

1 

/ 

static OM.descriptor bmoc ={ 

0M_0ID_DESC(0M_CLASS, MP.C.OBJECT.CLASS), 
{MP.GL0BAL.F0RM,0M_S.0BJECT_IDENTIFIER.STRING, 
{5,"\x2b\x6\xC6\x2a\x01"}}, 

OM.NULL.DESCRIPTOR }; 

\ 

1 

/* Section B*/ 

1 

/ 

static OM.descriptor pub.network.id = { 

0M_0ID_DESC( OM.CLASS, C.GNM.NAME.TYPE), 

{GNM.P.STRING, OM.S.GRAPHIC.STRING, 0M.STRING( "n" )}, 
OM.NULL.DESCRIPTOR }; 

\ 

1 

1 

1 

1 

static OM.descriptor pub.netid.ava = { 

0M.0ID_DESC( OM.CLASS, MP.C.AVA ), 
{MP_NAMING.ATTRIBUTE.ID, OM.S.OBJECT.IDENTIFIER.STRING, 
0M_STRING(0MP_0.GNM_A_NETW0RK_ID )}, 

{MP.NAMING.ATTRIBUTE.VALUE, OM.S.OBJECT, 

{0,pub.network.id}}, 

OM.NULL.DESCRIPTOR }; static OM.descriptor 
ds.rdn ={ 

0M_0ID_DESC(0M_CLASS, MP.C.DS.RDN), 

{MP.DISTINGUISHED.NAME, OM.S.OBJECT,{{0,ava}}}, 
OM.NULL.DESCRIPTOR }; 

1 

1 

1 

1 

1 

1 

/* Section C*/ 

1 

1 

1 

1 

1 

1 

static OM.descriptor ds.dn ={ 

0M_0ID_DESC(0N_CLASS, MP_C.DS.DN), 

{MP.DISTINGUISHED.NAME, OM.S.OBJECT,{{0,ds.rdn}}}, 
OM.NULL.DESCRIPTOR }; 

1 

1 

1 

1 

/ 
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static DM.descriptor bmoi 

\ 

0M_0ID_0ESC(0M_CLASS, MP.C.OBJECT.INSTANCE), 

l* Section D*/ 

{MP.DISTINGUISHEDJ ME, OH.S.OBJ ECT,{{0.ds.dn}}}, 

1 

OK.NULL.DESCRIPTOR >; 

/ 

static (^descriptor attr.id -{ 

\ 

OM_OID_DESC(OH_CUISS, HP_C.mRIBUTE.ID), 

1 

{MP.GLGBAL.FDRH, 0 B J ECT.ID E N TTFIE R_ STRING,{M P_B UF FE R$}}, 

I 

OK.NULL.DESCRIPTOR }; 

1 

static OM.deseriptor mod .list ={ 

\ 

/* Section E*/ 

OH.OID.DESC (DH.CLASS, HP.C.HODIFICmON), 

1 

{MP.ATTRIBUTE.ID, OH.S.OBJECT, {{0, attr.id}}}, 

1 

{MP.mRIBUTEJM.UE, OH_S_INTEGER, 10}, 

1 

{HP.HODIFY.OPERATOR.VALUE, OM.S.ENUHERATION,{{HP.REPLACE}}} 

1 

OH.NULL.OESCRIPTOR }; 

/ 

static OM.deseriptor argument ={ 

\ 

GH.OID_DESC(0H.CLI$S, HP.C.CHIS.SET.ARGUMENT), 

1 

(WP_BASE_MAN1GED.GB J ECT.CLASS, 0M.S.0BJ ECT ,{{0,bmoc}}}, 

/* Section f*/ 

<HP_BASE_ NAN A GED_ 0 BJ ECT JEMSTINCE, 0«^S^DBJ ECT,{{0,bmoi}», 

1 

{HP.MDDIFIC ATXQN.LIST, OH.S.OB JECT, {{0, mad JList}}} 

i 

QM.NULL.DESCRIPTOR }; 

/ 

MP.feature feature.list - { 

\ 

{OH.STRDIG (OMP.O.QH.OM), QM,OM.TRUE}, 

i 

{OH _ STRING {OH P_0_0 Mi_ HP _C0 MM ON _ PKG), QH.TRUE}, 

/* Section G*/ 

{OH_STRING(OHP_0.HP.CHIS.PKG)<0H.TRUE}, 

t 

{{0,NULL}, Ofl.F ALSE}}; 

/ 

us=mp_initiali 2 e(}; 

\ 

status=mp_v ersion(f ea t u r e.lis t, v s}; 

1 

om.create(HP_C.C0HTEIT ( OH.TRUE, us ,ficontext); 

1 

om.put(context,GH_REPLACE_ALL,context_opts,0,0,0); 

1 

om^c reate(HP.C.SESSION,0H_TRUE,u s,^session); 

1 

output(session,0H.REPLACE.ALL.session.opts,0,0,0); 

, It- 

mp.bind(session,ws,Abound^session); 

/* Section G*/ 

ofn.create(HP.C.CHIS.SET.ARGUMENT,OM.TRUE,ws,fiargl); 

1 

output(argl,OH.REPLACE.ALL,argument,0,0,0); 

1 

mp_ set.req(bound.session,context,a rgi, 

1 

k result,&invoke^id); 

1 

status=mp_ unbind (Atbound^session); 

1 

status"mp_shutdown(); 

/ 


Figure Bl Sample feature list definition (continued from page 98) 


that contains context variable defini¬ 
tions to be changed from the default 
state. Similarly, the session object must 
be created using om.c reate and om.put 
functions. 

The next function is mp.set.req. Its 
general syntax is: 

mp_set_req(bound_session l context, 
argument ,&result,&invoke_id); 

In the parameter list, the last two para¬ 
meters define the result. For a synchro¬ 
nous case (defined in the context 
object), the answer or result of the func¬ 
tion call is returned in the result vari¬ 
able, For an asynchronous case, a tag or 
identifying integer is returned in the 
invoke.id and the result parameter is 
meaningless. (It is the developer's 
responsibility to keep track of the 
invoke^ids after each asynchronous 
function call; this will be covered in a 
later article on programming for the 
LAN Netview platform,) The first two 
parameters, bound.session and context, 
are obtained from the mp.bind and the 
output respectively. The last argument 
parameter is a complex data structure 
describing the data to be modified. 

The argument form is described as a 
CMIS Set Argument with the following 
definition, obtained from the X/Open 
XMP specification for the CMIS Set 
Argument. (Only the required descrip¬ 
tors are shown): 

base managed object class 
base managed object instance 
modification.list 

Each descriptor has a syntax of 
object, which implies some level of 
nesting. While it is possible to construct 
the argument dynamically, it is given 
in Figure 9, Section F, as a static "pub¬ 
lic" definition, which will then be 
copied into a private definition with 
om_create and output. 

We are now faced with defining the 
objects bmoc, buioi, and mod .list. The low¬ 
ercase text indicates developer-chosen 
names. 

Notice that the definition of base 
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managed object class (bmoc object} is 
complete, in that a data value of type 
string has been assigned, (Within a real 
application a "real" class identifier 
would have to be selected. These class¬ 
es, defined in the LAN NetView Man¬ 
aged Object Catalogues, describe classes 
such as the operating system and the 
machine*} We can now proceed to the 
nested object bmoc, Because of the nest¬ 
ing, it is necessary to define the objects 
ds.drv ds_rdn, ADA, and networked. This 
procedure is shown in Figure 9, Sec¬ 
tions C and D> 

The definition of the base managed 
object instance is now complete. The 
data used in the instance descriptor is 
obtained from the specification of an 


specifications its structure is defined as: 

attribute^id 

attribute.value 

Enodify_operator_value\ 

The only object not completely 
described is the attribute id for the item 
to be modified. (It is important to note 
that all attributes are represented by an 
attribute id. For example, the buffer 
variable is actually identified by an 
attribute id of the form 13.66.77.62.2,) 

At this point, we have described the 
definition of a public object for a set 
argument; the code definition can be 
reused for all applications that need a 
set argument. Data portions can be 
modified using simple C notation. For 


In general, an argument structure must be 
defined only once. Once you have a set of 
these for each mp_xxx_req function, they 
can be easily reused. 


instance of an object at LAN NetView 
installation, (Only a portion of the 
instance is given in the previous fig¬ 
ures; a complete version can be found 
in the CompuServe OS2DF2 forum, 
library 13, under the name XMPDE- 
MO.C) Our next article will give a 
more thorough description of the rela¬ 
tionship between object instances and 
LAN NetView. The actual structural 
specification of the objects and 
sub^objects is found in the X/Open 
book under "base managed object 
instance." Everywhere an object is 
specified as a syntax, an additional 
level of definition must be accom¬ 
plished. Notice the relationship in the 
class name header and structure defin¬ 
ition, For example, an AVI object's class 
is NP.CJVA, (The descriptors comprising 
the class are again found in the 
X/Open book under the class name,) 
The last structure to be defined is 
the modification list. In the X/Open 


example, to dynamically change the 
attribute value to 30, the C code 
modjist 2 .value.integer=30; could be 
used. 

In general, an argument structure 
must be defined only once. Once you 
have a set of these for each np_m_req 
function, they can be easily reused. 

At this point, we can show the struc¬ 
tures associated with the CONTEXT and 
SESSION objects. Recall that we needed to 
define some data so the om_put could 
place these values in the objects. 

For SESSION, we need to include a title 
so a response can be routed back when 
a request is made. For context, we will 
specify confirmed mode and request 
that the result be returned synchro¬ 
nously, These can be seen as the 
req_title, session .opts, and context,opts 
definitions in Figure 9, Section A. 

Once the static structures are 
defined the code is relatively complete; 
it is time to build the argument and 


issue the set request. The complete 
code appears in the CompuServe 
OS2DF2 forum, library 13, under the 
name XMPDEMO.C. 

Creating the private version of the 
set argument is optional. Doing so, 
however, can simplify memory man¬ 
agement and improve performance. 

At this point, all coding necessary 
for the execution of set has been com¬ 
pleted. A complete code segment can 
be found in XMPDEMO.C, shipped as 
a sample with the LAN NetView Man¬ 
age product. 

HOUSEKEEPING 

One of the more troublesome portions 
of the framework, and of the X/open 
API in general, is that the function calls 
allocate space and return pointers to 
that space. This is true for results 
returned from the mp_xn_yyjf() API and 
the Gni_create and om.get function calls 
from XOM. Failing to delete structures 
no longer in use can lead to uncon¬ 
trolled growth in the memory neces¬ 
sary to run an application and eventu¬ 
ally cause a swapper.dat full error. It is 
easy to delete unnecessary structures 
with the om.deleteO function: 

omjtelete( result); 
omjielete(arg); 

The only caveat is that deleting a 
nonexistent entity can cause an abnor¬ 
mal exit from the program. On the 
other hand, if unused data is not delet¬ 
ed, an application will require more 
and more space to continue execution. 
As a rule, make sure that all public and 
private objects are deleted once they 
are no longer in use. Because each new 
call to an XOM/XMP function results 
in a new area being allocated, there is 
no advantage to keeping unused struc¬ 
tures around. 
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connect PARTS applications to on-line transaction 
processing power, PARTS is a client/server inte¬ 
gration toolset that enables visual application con¬ 
struction from prefabricated software components. 
Developers can use the CICS Wrapper to access 
mainframe transactions and data. 

Digitalk Inc 

Phone: (310) 645-1082 Fax: (310) 645-1306 

OeskMan/2. DeskMan/2 manages the OS/2 Work¬ 
place Shell, selectively saving, restoring, and 
migrating WPS objects, controlling object styles, 
deleting undeletable objects, generating REXX 
scripts, managing icons, and so on. A SOM exten¬ 
sion to the Workplace Shell, DeskMan/2 provides 
both GUI and programmatic interfaces, is CID 
enabled, and allows adminstrators to restrict 
access to individual DeskMan/2 features on a 
user-by-user basis. 

Development Technologies Lnc, 

Phone: (803) 790-9230 

Distributed Application#, IBM's Distributed Appli¬ 
cation/2 (DA/2) is a set of APIs that provide a 
consistent way to access interprocess and network 
communication functions under OS/2 2*0, making 
client/server applications easy to create. The APIs 
hide the complexity of the supported communica¬ 
tions protocols (APPC, NetBIOS, and OS/2 named 
pipes) and enable protocol selection at run time 
without requiring code changes. 


HALO Imaging Library. Media Cybernetics' HALO 
Imaging Library (HIL) offers developers the ability 
to add color, grayscale, and binary images to 32-bit 
applications quickly and easily* HIL provides 
more than 100 imaging functions and commands, 
enabling programmers to develop C programs 
that can read and store image files in several file 
formats and perform sophisticated processing of 
images in memory. A single HIL OS/2 worksta¬ 
tion license costs $599.00. 


Media Cybernetics Inc, 

Phone: (301) 495-3305 Fax: (301) 495-5964 


KfShell. A workflow process modeling and enact¬ 
ment tool that takes advantage of modeling tech¬ 
niques like IDEF, UES Computing Environments' 
KlShell is the first commercial process manage¬ 
ment tool that can declaritively model work activ¬ 
ities and synchronization, user responsibilities, 
and information, and tool use in a reengineered 
business process. K1 Shell also enhances software 
engineering environments by integrating method¬ 
ology process support, software project and struc¬ 
ture information, and multi-vendor CASE tools. 


LIES Corp, 

Phone: (614) 792-9993 Fax: (614) 792-0998 

XPRO 5M L A Prolog system for building intelligent 
applications that run in the 32-bit OS/2 environ¬ 
ment, Rational Visions' XPRO 5.0 is designed to 
work with developers' C or C++ code. Consisting 
of the XPRO Developer, the XPRO Engine, and the 
XPRO Rule Compiler, the system will cost $399 
until December 31,1993; after that $499. 


IBM Corp. 

Phone: (800) 342-6672 


Rational Visions 
Phone: (602) 846-0371 
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APPLICATIONS 

C-Kermit. Columbia University's C-Ker- 
mit is a full-function communications 
software package for OS/2. With a built-in VT102 
terminal emulator with screen, screen rollback, and 
color and printer control, C-Kermit allows easy 
switching among applications. Distribution fees 
range from $45.00 to $220.00; call for a catalogue. 



IBM ARTIC960. IBM's first 32-bit communications 
coprocessor adapter card for Micro Channel-com¬ 
patible systems such as the IBM PS/2 enables 
computers to communicate much more quickly. 
ARTIC offloads compute-intensive tasks, resulting 
in increased communications capabilities and 
improved performance. Cards start at $2,200. 

IBM Corp. Phone: (800) 342-6672 


Kermit Distribution, Columbia University 
Phone (212) 854-3703 Fax (212) 662-6442 

FAR Fax. A multi-application fax platform from Far 
Systems, FAR Fax is a stand-alone fax server for 
automating functions such as fax broadcasting or 
retrieval. FAR Fax supports Brooktrout fax boards. 

Far Systems Inc. 

Phone: (414) 563-2221 Fax: (414) 563-1865 


IBM X Window System Client Kit and OS/Windows 
Access. These two new products from IBM let users 
run X Window System applications and DOS or 
Windows TCP/IP applications, respectively, on 
OS/2. The X Window kit also lets applications run 
from OS/2 or another X Window server, while 
OS/Windows Access can also run applications 
written for DOS 2.1 in an OS/2 DOS session. 

IBM Corp. Phone: (800) 342-6672 


DEVELOPER SUPPORT 

OS/2 Screen Saver Contest BocaSoft, The 
IBM Developer Connection CD, and 
OS/2 Developer announce the 1993 OS/2 Screen 
Saver Developer Contest. Create an OS/2 screen 
saver module and win a $1000 grand prize, OS/2 
software products, T-shirts, and more. Entries will 
be accepted in three categories: 

• Programmer—Submit working code for a 
screen saver module using the BocaSoft Wipe- 
Out Developer kit. 

• Graphic Artist—Submit a screen saver story¬ 
board with computer artwork included. 

• Video Artist—Submit a video to be converted 
into an Ultimotion movie as a screen saver 
module. 

Entries will be judged on appearance, originality, 
and functionality. BocaSoft will award prizes to the 
top three entries in each category. The grand prize 
and category winners will be selected by a panel of 
industry experts and announced at the Software 
Development Conference in March 1994. Contest 
results will be published in a future issue of OS/2 
Developer. 

Details and an official entry form are available 
on CompuServe in the BocaSoft section of the IBM 
OS/2 Vendor Forum in CONTEST.TXT. For addi¬ 



tional information, contact BocaSoft at 71333,3617. 
Mail entries with entry forms to: 

1993 OS/2 Screen Saver Contest 
117 NW 43rd St. 

Boca Raton, Fla. 33431 

Entries must be received before February 28,1994. 

IBM AskPSP Expert Systems CD-ROM. IBM Personal 
Software Products' AskPSP is an expert systems 
application that uses intelligent retrieval technolo¬ 
gy to provide OS/2 developers with answers to 
technical questions and problems. AskPSP, avail¬ 
able free as part of a pilot program, provides an 
on-line "help desk" that responds to natural lan¬ 
guage description of problems with answers 
culled from a library of case histories or additional 
questions that refine the search. 

For a free copy of Ask PSP, call IBM PSP Devel¬ 
oper Assistance at (407) 982-6408. 


To Appear In Product Watch 

If you would like your product to appear in a 
future Product Watch, please fax a short press 
release to OS/2 Developer Product Watch, (415) 
905-2234. 

Press releases will be edited. Space is limit¬ 
ed; OS/2 Developer carinot guarantee the 
inclusion of any product in these pages. 


NOVEMBER/DECEMBER 19 9 3 





















Software Toots 


Software Installer for OS/2 lets you create CID-enabled LAN installations, shrink-wrapped disk or CD-ROM 
installations, or installations from a mainframe. BY ken GREENLEE, RUSSELL SAGRAVES, ruth willenborg, 
and BRIAN YOUNG 


Software Installer: 
Installations Made Easy 



(l-r) Russell Sag raves, Brian Young, 
Ruth Willenborg, Ken Greenlee 


K ou've written your application and now 
you need an installation program* At a 
minimum, your customer is expecting an 
easy-to-use program that provides features such 
as allowing a choice of where to 
install your product checking for 
the required hard disk space, and 
updating the user environment* In 
addition, many customers now 
expect a choice of disk, CD-ROM, or 
LAN install. Users can also be frus¬ 
trated if an install program does not 
provide an automated deletion to 
undo installation. In the LAN envi¬ 
ronment, customers may even want 
to install your application unattended from a cen¬ 
tralized location. 

Providing this level and variety of installation 
function is expensive and time-consuming* You 
would rather spend your time improving your 
application's function, but because an installation 
program is a user's first impression of your prod¬ 
uct meeting user expectations is critical. 


SOFTWARE INSTALLER FOR OS/2 

Software Installer for 05/2 addresses user expec¬ 
tations about installation* For example, the unat¬ 
tended LAN install is supported through compli¬ 
ance with IBM's Configuration, Installation, and 
Distribution (C1D) architecture* The CTD architec¬ 
ture requires each application to support the fol¬ 
lowing requirements: 

■ Transfer of product to a repository 


* Support of response files 

• Support of command line parameters 

• Generation of error and history logs 

* Support for return codes to a Software Distrib¬ 
ution Manager (SDM). 

CREATING YOUR INSTALLATION PROGRAM 

Once you've decided to use Software Installer, you 
need to enable your product. Users won't know 
that you are using Software Installer because your 
customized installation becomes embedded within 
the finished product* You can also provide the 
Software Installer to customers; they can use it 
later to restore, delete, and apply fixes to your 
application* 

Before beginning the enablement process, you 
need to make decisions about how your product 
will be packaged and how you want to configure 
your customer's environment: 

1 On which media (CD-ROM, disk, LAN, or host) 
will my product be delivered? 

2* Will my product be packaged as one product or 
separate products? 

3. Does my product have components? (A com¬ 
ponent is a portion of the product that the cus¬ 
tomer can optionally install.) 

4. How many directories does my product 
require? 

5. Does my product require changes to the cus¬ 
tomer's CONFIG.SYS or 052.INI? 

6. What Workplace Shell objects {such as folders 
or programs) does my product need? 

As an exercise, we will take you through the steps 
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we went through when we enabled Software 
Installer to itself* We asked ourselves the same set 
of questions and arrived at the following answers: 
1. Disk media 
2* One product 

3. Consists of four components {base install pro¬ 
gram, online reference, sample enablement 
files, and disk generation utility) 

4. One directory 

5. No CONFIG.SYS/OSZINI changes 

6. One main folder on the desktop containing pro¬ 
gram objects for the install program and related 
utilities, the on-line reference, samples, and the 
disk generator. 

Now we are ready to begin the enablement 
process. 

ENABLEMENT STEPS 

Enabling to Software Installer takes six basic steps: 
1. Rename Software Installer product files 
2* Customize the initial screen 
3* Build a customized copy of Software 
Installer 

4* Create catalogue, package, and description 
files 

5. Create your product files 

6. Package your product. 

A full description of these steps can be found in 
the online reference provided with Software 
Installer. 

For our exercise, the enablement steps are 
shown in Figure 1. Let's look at each of them* 

RENAME SOFTWARE INSTALLER 
PRODUCTFILES 

Most Software Installer product files are shipped 
with a prefix of EPF; before you ship Software 
Installer with your product you must rename the 
files. Using the ISREN.CMD rename utility 
shipped with Software Installer, supply your own 
three character prefix and a directory for the 
renamed files. 

CUSTOMIZE THE INITIAL SCREEN 

This step is probably the most fun* You get to cre¬ 
ate bitmaps that are used on the initial Software 
Installer screen. You can use special effects to 
move the bitmaps on the screen and make them 
appear in slices or dissolves* 


All screen customizations are done in a file 
called 1IRCRC* You will want to use the supplied 
I1RC.RC file as a starting point* 

The customized screen used by Software 
Installer is shown in Figure 2. 


Rename 




Customize 
Initial Screen 


u 




figure t Steps for enabling to Software installer 


BUILD A CUSTOMIZED COPY 
OF SOFTWARE INSTALLER 

This step builds your customized copy of Software 
Installer to ship with your product. You invoke the 
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supplied BLDIMST.CMD utility to cre¬ 
ate a packed XNSTALL.BL file containing 
all of the customized files. 

The important thing to remember is 
that before you invoke the 
BLDINST.CMD build utility, you need 
to be in the directory in which your 
renamed copy of Software Installer was 
created. 


CREATE CATALOGUE, PACKAGE, 
AND DESCRIPTION FILES 

This step will be the most time-con¬ 
suming; you'll need to familiarize your¬ 
self with the terminology and syntax of 
the catalogue and package files. The 
terminology used in catalogue and 
package files is entry type and keyword. 
The syntax of an entry type is: 


entry type 

keyMordi=valuei, 

keyword2=value2, 

* * keywordn=valuen 

Use entry types to select Software 
Installer features and keywords to 
define how the feature works. 

Catalogue File . A catalogue file is a text 
file containing information about your 
product; this information is used by 
Software Installer to install your prod¬ 
uct. General product information such 
as name and version/release/modifi¬ 
cation number (VRM) must be provid¬ 
ed for all products. 

The answers you gave to the enable¬ 
ment questions will help you decide 
which additional entry types and key¬ 
words to use. 

The answers we provided to the 
enablement questions and the corre¬ 
sponding catalogue file entries to use 
are shown below: 

1. Disk—use the DRIVE: value keyword 

2. One product—use one PACKAGE entry 
type. 

As an example, a subset of the actual 
catalogue file is shown in Figure 5. For 
a complete list of catalogue file entry 
types, see Table 1. 

Package File l A package file is a text file 
that contains information about your 



Figure Z Software Installer s customized screen 



Figure 3, Software Installers Install-directories dialogue 


product files; this information is used 
by Software Installer to install your 
product and to customize your cus¬ 
tomer's workstation. General product 
information such as service level must 
be provided. 

The answers you gave to the enable¬ 


ment questions will help you decide 
which additional entry types and key¬ 
words to use. 

The answers we provided to the 
enablement question and the corre¬ 
sponding package file entries to use are 
shown here: 
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1. Disk—use the DRIVE: value on the 
SOURCE keyword of the FILE. 
Entry type—use a DISK entry for 
the one disk we ship. 

3. Yes—use four COMPONENT 

entries, one for each component. 

4. One directory—our PATH entry 
contains only the FILE keyword. 

6. One main folder—use the CRE- 
ATEWPSOBJECT and DELETEWP- 
SOBJECT exits. 

For example, a subset of our Software 
Installer package file is shown in Fig¬ 
ure 6. For a complete list of Software 
Installer exits, see Table 2. For a com¬ 
plete list of package file entry types, see 
Table 3. 

Description File. A description file is a 
text file that contains a brief description 
of the product. The text in the descrip¬ 
tion file is displayed exactly as you 
type it. The only formatting that occurs 
is word wrapping. 

For a simple disk installation, you 
do not need a description file. 

COLLECT YOUR PRODUCT FILES 

In this step, you should move all your 
product files to a central location for 
packaging. 

PACKAGE YOUR PRODUCT 

In this step you create a master copy of 
your product that will be shipped to 
customers. If you are shipping your 
product on disk, a disk generator utility 
is provided to place your files onto the 
disks. 

If you decide to make your product 
available on both disk and CD-ROM, 
you will need two package files: one for 
the disk installation and one for the 
CD-ROM installation. 

INSTALLING YOUR PRODUCT 

To start an installation from a disk, 
insert the disk into the A: drive and 
enter A:\INSTALL Your installation will 
display your customized screen, 
prompt the user whether to update his 
or her CONFIG.SYS, prompt the user 
to select the components, display a 
progress indicator as the component 
files are installed, and display a mes¬ 


sage when the installation is complete. 

See Figure 3 for a picture of Soft¬ 
ware Installer's Directories dialogue. 
See Figure 4 for a picture of the 
Progress dialogue. 


LAN AND HOST SUPPORT 

For the LAN environment, both reposi¬ 
tory and server/requester scenarios are 
supported. The repository scenario 
allows the application to be installed on 



The GammaTech 
Utilities are 
designed to enhance 
and complement 
your OS/2 system. 
These utilities provide 
the ability to perform 
vital maintenance 
and recovery 
operations easily 
without extensive 
technical knowledge. 
Use GammaTech 
Utilities for your 
critical data or you 
might lose it. 



GammaTech Utilities 
PT for OS/2 


• Undelete Erased Files 

• Optimize HPFS and FAT Volumes 

• Backup INI and Desktop Files 

• Recover HPFS Volumes 

• Protect and Backup Boot Sectors 

• Identify and Mark Bad Sectors 

• Reconstruct Boot Sectors 

• Protect/Lock Files 

• Permanently Erase Sensitive Data 

• Mass Delete Selected Files 

• Sort FAT Directories 

• View and Edit Selected Files 

• Disk Sector Edit (ASCII or Hex) 

• Display Volume Information 

• Alter File Attributes 

• Add Comments to Files 

• Display File Fragmentation 

• Display Directory Information 

• SAA/CUA Compliant PM Interface 


For OS/2 Version 2 


VISA. MasterCard. American Express, CO D • Overnight Service Available 

(405) 947-8080 • Fax (405) 632-6537 

SofTouch Systems, Inc., Workstation Division 

1300 S Meridian, Suite 600, Oklahoma City, Oklahoma 73108 
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Figure 4 r Software Installer's progress dialogue 


CATALOG 

NAME = 'Software Installer % 

DESCRIPTION = 'This catalog contains the Software Installer, This 
product allows you to create a graphical installation for 
any workstation product/ 

PACKAGE 

NAME = 'Software Installer', 

NUMBER = '5621-434/ 

VRM * '010200/ 

FEATURE = '0000/ 

PACKAGEFILE = 'DRIVE: EPFISPKG.PKG/ 

PKGDESCRFILE = 'DRIVE: EPFISDSC.DSC/ 

SEE = '2500000' 


Figure 5. Subset of Software Installers catalogue file 


a LAN server that is the source of the 
install for all workstations that have 
access to the server. In this scenario, the 
entire application would be transferred 
to each requester that initiates an install. 

The server / requester scenario 
allows a part of the application to be 
installed on a server and then shared 
by all requesters. This part only exists 
on the LAN server and is never 
installed onto the requesters. A sepa¬ 
rate part of the application that can't be 
shared is installed on each requester. 
Depending upon how the application 
uses Software Installer, this piece can 
be installed on each requester from the 
server or from one of the other media, 
such as a CD-ROM, 

For the host environment, Software 
Installer supports installation from a 
system running one of the following 
operating systems: 

• Multiple Virtual Storage (MVS) 

• Virtual Machine (VM) 

• Operating System/400 (OS/4O0) 
with IBM PC Support/400 

• Virtual Storage Extended (VSE/ 
ESA) 1.3.0. 

ADVANCED TOPICS 

Maintenance Functions. Software Installer 
includes maintenance functions for 
updating, restoring, and deleting. You 
do not need to make any special modi¬ 
fications to your catalogue or package 
file to access these functions; they may 
be accessed through either a command 
line parameter or a Software Installer 
dialogue. 

User Exits , You may be thinking that 
your product installation is too specific 
to be handled by a generic installation 
package. Perhaps you bring up dia¬ 
logues at various points of your current 
installation to prompt for information 
about the user's system or the user's 
choice of configuration options. Then 
you use this input to finish installation 
and configuration of the product. 

Software Installer is capable of han¬ 
dling even the most unique installation 
processes. This is done by allowing you 
to execute your own exits during instal¬ 


lation. You can code short exits to per¬ 
form tasks, such as updating configu¬ 
ration files used by your product, or 
bring up dialogues to prompt for addi¬ 
tional information. For example, you 
could code an exit to bring up a dia¬ 
logue to prompt for the type of printer 
the user has. 

Inter-Exit Communication, Now that your 
user exit has obtained the customer 
information you needed to continue 
with the install, how do you reference 
this information? 

Exits can communicate back to Soft¬ 
ware Installer and, as a result, to later 
exits during product installation. Soft¬ 
ware Installer provides APIs that 
enable your exits to store and retrieve 


values for variables you wish to set. By 
referencing the values of these vari¬ 
ables in the package file, you can deter¬ 
mine whether a file is to be transferred, 
a configuration file updated, or any 
other action taken. For example, you 
may wish to transfer a certain printer 
driver only if the user selected the 
printer in a previous user exit's dia¬ 
logue. By setting a variable to the name 
of the printer selected, you can refer¬ 
ence the variable later in a FILE entry 
type to determine whether the file 
should be transferred. 

CONFIG.SYS Manipulation. Software 
Installer allows advanced manipulation 
of the CONFIG.SYS file. Using the ADD- 
CONFIG and UPDATECQNFIG entry types, you 
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SERVICELEVEL 
LEVEL = '000000' 

DISK 

NIUE = 'Software Installer - Diskette r, 

VOLUME = 'IBBENUOr 

PITH 

FILE - 'C: /IBS', 

FILELIBEL - 'Installation directory' 

* Product Folder 
COMPONENT 

NIME = 'Product Folder% 

ID = 'PRODFLD', 

DISPLAY =10', 

SIZE = '100(50' 

* Create the folder 
FILE 

EKITWHEN = 'INSTALL 11 UPDATE II RESTORE', 

EXITIGNDREERR = W t 

EXIT = 'CREITEyPSOBJECT WPFolder "Software Installer" 
<WP_DESKTOP> R 

"ICONFXLE=JiEP FIFIL EDIRX/ /bin //epf iicol. ico; 

OB JECTID=<EPFIFLD>"' 

* Installation Program 
COMPONENT 

NAME = 'Installation program', 

ID = 'INSPROG', 

REQUIRES = 'PRQDFLD', 

DISPLAY * 'YES', 

DESCRIPTION = 'Select the "Installation program" component to 
install all files of Software Installer that will allow you to 
create a renamed copy of Software Installer and to perform the 
installation, jiaintenance, and delete functions of Software 
Installer/, 

SIZE = '2120000' 

* Register the Installation Utility 
FILE 

EXXTVHEN = 'INSTALL II UPDATE If RESTORE', 

EXITIGNOREERR = 'NO', 

EXIT = 'CREITEWPSOBJECT ypProgram "InstaUaUon Utility" 
<EPFIFLD> R 

"EIENIME<MD. EXE; OBJECTID=<EPFINSTS>; 

$T I RTUPDIR=KEPFIFILE DIR/,// bin; 

PARAMETERS 2 ^ , /EPFIFILEDIRX//biJi//epfinsts.exe;"' 

FILE 

EXITVHEN = 'DELETE', 

EXITIGNOREERR = 'YES', 

EXIT = 'DELETEWPSOBJECT <EPFINSTS>' 


F??tprints 


CE24 9 6^/? 
6 5CA Bt*.»FDB3y 



for OS/2 

• Tired of slow debuggers? 

• Can’t duplicate a reported 

customer problem? 

• Need to verify all paths of 
execution without using print/? 

• Trying to support code in 
Dime Box, Texas, from 
Brooklyn, New York? 

Footprints is the product for you! 

Dynamic debugging 
Online monitoring/Offline analysis 
Realtime systems 

Telecommunications 

Multi-thread / multi-process 
Remote support and postmortems 

Dynamically select which 
portions of code to trace - in 
a live user environment! 

Footprints is simple to use! Just include a 
header. Link to a DLL. You’re ready to call 
Footprints and begin capturing any or all 
the data you require. Footprints doesn't 
bog down your code with constant tracing or 
file I/O. The tracing only gets activated 
when and where you hyjw* it. From our 
friendly PM interface, you dynamically 
turn on one or more of up to 64 separate trace 
ids that control what data you are tracing. 
You can then view the time-stamped data in 
memory as it whizzes by, or view it at your 
leisure from a file days after the fact. 

ONLY $ 99 

Call 713-871-1448 now! 

V1SA/MC or send a check to 

Hardy Software Systems, Inc. 

4801 Woodway, #415 * Houston, TX 77056 
s/h charge $ 5.95 
Total Cost $104.95 
Texas residents add 8.25% sales tax. 

Requires OS/2 2,0 or later. 



Figure 6. Subset of Software Installer's package file (continued on page 111) 
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The Impact Formatted Eatryfields are 

c Eompleiely new window class which dbws 
the developer to specify a formal string 
when the entryfield is created. Formatting 
tan be used for fields like Phone Number, 
Dates, Social Security Number, etc. 

The Impact Forma lied Entry field 
dynamically formats itself as the 
user inputs data. 

Tie Impact Formatted Entryfield 
support assures uniformity in 
data entry. 


The developer has complete control to create 
custom fields like; 

* Numeric entry only 

* Alpha characters only 

* Special delimiting characters 

* Value ranges 

* Currency support 
and, much more. 

Easy to use! Just change the window doss in 
your resource file. 

Download fre« demo ol 
Impoei Enlryfields Fom our BBS 
(8IB] 879-7405 

Add Impact to your application 


| IMPACT SOFTWARE 


5139 Kdfhni Rd 
Suilt 330 
Agwic HSj 

a slid 


To order (ill or write 

limn 5592 
ftf (1111379 5593 


Invest a stamp 



Save a bundle 


For the price of a stamp, you can get the latest edition of the federal gpvemmente free 
Consumer Information Catalog listing more than 200 free or low-oast government 
publications an topics such as federal benefits jobs, health, housfog education, cars, 
and much more. Our booklets will help you save money, make money, 
and spend it a little more wisely. 

So stamp out ignorano?, and write today for the latest free Catalog 
Sold your name and address toe 

Consumer Information Center 
Department SB 
Pueblo, Colorado 81009 


A public wvk-e of this publkrtkm jots! thr Omumcr Iri^uiiDitOMiTirftfwtJS Gcntril Service* Aduttni 

















































Figure 6. Subset of Software installers package file (continued from page 109) 


CATALOG 

Provides a name and description of what the catalogue 
file contains 

INCLUDE 

Specifies an additional catalogue file to include into the 
primary catalogue file 

PACKAGE 

Specifies the product name and numbers, as well as 
the names of the package and description files 

Table 1. Catalogue file entry types 


may add a new line or update an 
already existing line. You may position 
your new item before or after another 
item that you specify. You may also 
replace the first last or all occurrences 
of a line with a new line. You can 
ensure that a new line is added only if 
it does not exist already. Finally, should 
the user delete your product the CON¬ 
FIG.SYS updates can be undone. 



User-Supplied Pack Utility. Files can be 
packed with either the supplied pack 
utility or a utility of your choice. You 
need only supply in the package file or 
Disk Generation Utility the name of the 
utility you wish to use in place of the 
default 


CONCLUSION 

Software Installer for OS/2 provides a 
rich, functional installation and main¬ 
tenance program for applications. 
Your customers will get a great first 
impression of your product, and you 
can spend your time enhancing your 
product. 


REFERENCES 

For detailed information on creat¬ 
ing your installation programs, 
please refer to the Software Installer 
for OS/2 Reference and the product 
samples. 

Software Installer for OS/2 is cur¬ 
rently available in English and 
Japanese, For more information, 
call (800) 426-2279 (919469-7763) 
or fax 919469-7423, 

Questions are also addressed on 
the OS/2 Developer forum 
(OS2DF2) on CompuServe section 
S and the INSTALL2 forum on the 
OS/2 Talkiink BBS, 
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Exit 

Function 

ADDDU 

Add application name/keyname pairs or modify information in the OS2.INI system file. 

AODPROFILE 

Add application mrne/keyname pairs or modify information in a specified application profile file. 

CREATEVPSflBJECT 

Create a workplace object, such as a folder. 

DELETEFILES 

Delete data files your application created. 

DELETEINI 

Delete application names from the QS2.IN1 system file. 

OELETEPROFILE 

Delete application names from a specified application profile file. 

DEIETEYPSOBJECT 

Delete a workplace object. 

DEREGISTERKPSCLASS 

Deregister an OS/2 object class. 

EXEC 

Start a user exit. This exit may be a program (.EXE) or command file (.CMD). 

REGISTERWPSCLASS 

Register an OS/2 object class. 

SETIftR 

Set installation variable for use later in the package file or in user exits. 


Table 2. Software Installer exits 



AODCOra 

Specifies lines to be added to, deleted from, or replaced 
in the user's CONFIG.SYS file 

COMPONENT 

Identifies a separately installable part of the application 

DISK 

Associates a user-friendly name to an installation disk 

EKH 

Specifies the DLL to be used for installation exits 

FILE 

Identifies files to be installed and exits to be run 

INCLUDE 

Specifies another package file to be included into the 
current one 

OPTIONS 

Specifies message text to be displayed after a successful 
install, update, restore, or delete 

PACKFILE 

Identifies a packed file that contains multiple product files 

PATH 

Specifies the paths to be used for transferring all files 

SERVICELEVEL 

Specifies the level of sendee of the product files 

UPDATECONFK 

Specifies information to be added to existing CONFIG.SYS 
lines 


Table 3. Package file entry types 
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Discover why FoxPro, Clipper, 
and dBASE were all written in C. 


#here is a good reason why 
•your database language was 
developed in C. In fact, there 
are many good reasons. 


C code is small, C code is fast* C code is 
portable. C code is flexible. C is the 
language of choice for today's professional 
developer With the growing complexity of 
database applications, C is a realistic 
alternative. Now with CodeBase 5.0, you 
can have all the functionality* simplicity and 
power of traditional database languages 
together with the benefits of C/C++. 


C speed ■ fast code, true executables... 

FoxPro, Clipper, and dBASE were written 
in C primarily for speed. But those compilers 
don't really compile, they combine imbedded 
lan guage i n terp reters into you r . EX E. N o w 
that's slow. For dazzling performance you 
need the true executables of C. With 
CodeBase you get the real thing. C code. 
Consider the following statistics, from the 
publisher of Clipper: 





"Sieve of Erastothenes 

Benchmark for Prime Number Generation 
Shows C to be incredibly faster! 


C size ■ small executables, 
no added overhead... 

FoxPro, Clipper and dBASE would like yon 
to believe you need their entire development 
system to build database applications. But 


remember, those products are all written in 
C, So why do you need to lug all their extra 
code around? You don't. CodeBase is a 
complete DBMS, in C. No fat executables 
stuffed with unused code. No runtime 
modules. No royalties. Just quality C code. 
CodeBase is just what you need. 


data files w ith any logical dB ASE expression. 
Our new Bit Optimization Technology 
(similar to FoxPro's Rushmore technology! 
uses index files to return a query on a 1/2 
million record data file in just a second. 
Automatically take advantage of this query 
performance by using our new r CodeReporter: 


C portability-ANSI C/C++ 
on every hardware platform... 

No other language exists on more platforms 
than C/C++. Why rewrite your entire 
application for DOS, Windows, Windows 
NT. OS/2 or UNIX? With CodeBase the 
complete C source code is included, so you 
can port to any platform with an ANSI C or 
C++ compiler. Now and in the future. 

dBASE Compatible data, index 
and memo fifes... 

You want the industry standard. You need 
compatibility. Sure, dBASE is the standard, 
but every dBASE compatible DBMS 
product uses its own unique index and memo 
file formats. Only CodeBase has them all: 
FoxPro (.cdx), Clipper (.nix), dBASE IV 
(.mdx) and dBASE 111 (.ndx). Now it’s your 
choice, we re compatible with you. 

Announcing 
CodeBase 5.0 

The powe r of a complete DBMS, the benefits of C 

NEW - Multi-user sharing with 
FoxPro, Clipper and dBASE... 

Now your multi-user C/C++ programs can 
share data, index and memo files at the 
same time as concurrently running FoxPro, 
Clipper and dBASE programs. No 
incompatibilities. No waiting, 

NEW - Queries & Relations 
1000 times faster... 

CodeBase 5,0 now lets you query related 


[V» <■++* tw PUM tfrt 

:■ T- - -- 

Ptodurt Mn Sumrt 

Product Sale* Sunmury 

Um&HhAc Ot^ik: h. Htiftc <lta 

itai mr 


n«biT Q*,«,■ tkfe. 

Firinl BhwW FaH 

OikAw 41 P-IUB 


111 111, III tHJBUB 

Wirt, 4. 


i H tSSi iSSli* 

>Wklt Dh. IW 



tL . lAfik i ini^r JLAAmv 

DMm* H tllHiit 

unci 

51 

■ m 114 HMMr 



To use CodeReporter. 



simply draw your report, then include it in any 
program you write . Call 403/4S7-24I0 now for 
your FREE working model of CodeReporter. 

New - Design complex reports 
in just minutes... 

Our new Code Reporter takes the painstaking 
work out of reports. Now simply design and 
draw reports interactively under Windows3.1, 
then print or display them from any DOS, 
Windows or UNIX application, 

SPECIAL * FREE CodeReporter 

Order CodeBase 5 before June 30, 1993 
and receive CodeReporter for tree! This 
offer includes our no-risk, 90-day money 
back guarantee, so order today! 



5.0 

TT» C/C++ Library tor DataBase Management 

Call Now 
403-437-2410 
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More 


Demand for break¬ 
through, .52-bit 
OS/2® a p pi ica ti on s 
is developing into a 
huge opportunity. 

That's why we developed Borland " C++ for OS/2®—the 
easiest-to-use C++ development system for world-class 
OS/2 applications. 

Borland C++ for OS/2 is 
a complete application devel¬ 
opment system. It combines 
an industry standard-setting Borland C++ compiler and 





tools with the industrial-strength power of OS/2, 
so building C and C++ OS/2 applications is faster 
and easier than ever before, Borland s highly integrated 
graphical environment and visual tools raise pro¬ 
ductivity to a whole new level. The new, integrated 
Turbo Debugger GX finds bugs fast. And you can 
take full 
advantage of 
the full power 
of OS/2 with 
32-bit code 
generation, 

pre-emptive multitasking and state-of-the-art 
optimizations. 

To help speed your development along, Borland 
C++ gives you access to the largest resources of 
OS/2 libraries, controls and other add-ins. So if you're 
looking fur fast, easy ways to create exciting, new, 
32-hit OS/2 applications, get Borland C++ for OS/2 
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Borland C++ 
for OS/2 has 
mverything 
pY>ti need to 
mucceed in 
1 creating lead¬ 
ing-edge OS/2 
applications. 


today—and see what develops* To order or to find out 
more about OS/2 2.1 or Borland C++ for OS/2, call 
1 800 3-1BM-OS2. In Canada, call I 800 465-7999* 

Operate at a higher level. 


Borland C 


IBM and OS/2 are registered trademarks and "Operate at a higher level" is & trademark of International 
Business. Machines Corporation Borland is a registered trademark ol Borland International. Inc 
©1993 IBM Carp 























